Document:org manual
Author:bsp
Date:2020

1 Table of Contents

2 Introduction

org is a free and open source text file processor and document generator that is suitable for
org supports conversions between / to the following file formats:
alt
org is loosely based on the Emacs org-mode text format (.org files) but can also handle todo-list style textfiles (todo.txt), or any mixture between these two formats.
As a standalone command line tool it works with all text editors, including Emacs, VIM, NotePad++, iA Writer, Byword, Ulysses, Markor, and many others.
In addition to text files, org supports lossless conversion to and from SimpleMind Pro .smmx mind maps.

3 Prerequisites

org is written in tks, a free and open source scripting language, with precompiled binaries available for x64 Windows and Linux. tks can also be compiled for MacOS and ARM-based Linux systems.
tip_l
On Windows it is recommended (but not required) to also install MSYS2 to get access to standard *nix tools like BASH and make.
Alternatively, the WSL 2 Windows Subsystem for Linux can be used (although MSYS2 has a better integration into the Windows environment, in my opinion).

4 Command line options

-o outputfileSet output pathname.
The output file format is derived from the output file suffix (.org, .txt, .md, .smmx, .csv, .html)
-so,--stdout fmtWrite output to stdout. fmt must be one of org, txt, md, smmx, csv, html.
-d,--debugEnable debug output
-n,--dry-runDon't actually write any output files
-w,--warningsShow warnings (e.g. unresolved other-project tasks)
-neh,--no-emacs-headerDon't write emacs -*-mode and #+TODO headers (e.g. when creating an include file)
-p,--privateDon't export sub-trees that are marked private
-raw,--rawutf8Preserve UTF-8 characters (don't convert to CP1252)
-har,--html-auto-refreshAdd auto-refresh code to generated HTML page
-ht,--html-templateSelect HTML template file. See templates
-t,--todo levelForce todo.txt style output for all nodes that are nested deeper than level
-g,--org levelForce org-mode style output for all nodes up to (and including) level
-psp,--prefer-simplified-propertiesUse simplified syntax for special properties like depends, allocate, ..
-txf,--textformatting
Convert text formatting (bold, italic, underline, strike-through, subscript, superscript)
note_s
without this option, all text-formatting will be passed on as-is
-tf,--tagsfirstPlace tags before topic title
-tl,--tagslastPlace tags after topic title (org-mode style, default)
-tarsc,--tags-always-require-start-colonDo not allow tags without start colon
-dpso,--debugprintsuboutlinePrint document outline to console (skip todo.txt style child nodes when parent is org-mode style node)
-pd,--preferred-date create|finish|scheduled|deadlineSets preferred date source when exporting to .smmx mindmap
-siao,--smmx-info-as-orgConvert info nodes to .org formatted text note when exporting to .smmx (default)
-siat,--smmx-info-as-topicsConvert info nodes to actual nodes when exporting to .smmx
-f,--filter tagsFilter out all nodes whose tags do not include at least one of the given tags (comma or colon separated list)
-fa,--filterall tagsFilter out all nodes whose tags do not include all the given tags (comma or colon separated list)
-if,--inversefilter tagsBlacklist all nodes whose tags include at least one of the given tags (comma or colon separated list)
-sf,--state-filter statesFilter output by state(s), e.g. TODO, ACTV
-pf,--property-filter filterAdd property filter, e.g. allocate=*bsp*
-s,--scheduleEnable scheduler mode (project plan export, .csv or .html output)
-sy,--schedule-yearsSet maximum project duration (default = 5 years)
-srv,--schedule-resource-viewCreate resource view table (in addition to project plan)
-now,--now dateOverride current date (default=today) (in scheduler mode)
-tsgp,--time-sheet-grace-periodMaximum number of calendar days until tracked working hours override planned / ideal task working hours (default=10)
-sbsd,--sort-by-start-dateSort report tasks by start date (in scheduler mode)
-ssg,--schedule-skip-gantt]Skip Gantt graph generation (in scheduler mode)
-ssgo,--schedule-skip-gantt-overview]Skip Gantt graph overview generation (in scheduler mode)
-stl,--schedule-traffic-lightsInclude traffic lights column in HTML plan (in scheduler mode)
-stls,--schedule-traffic-lights-stateDerive traffic light status from working state instead of status property
-stt,--schedule-task-titlesShow task titles instead of ids in HTML plan (in scheduler mode)
-ms,--milestone milestone_task_idCreate schedule only for the given milestone task
-sde,--set-default-effort-for-all-working-state-tasksAssign default effort to all tasks with state TODO, ACTV, TEST or DONE.
tip_s
Useful for converting plain todo.txt files to HTML plans
-afg,--autofold-task-groupsEnabling effort folding when task has sub tasks.
tip_s
Useful for converting plain todo.txt files to HTML plans
-nr,--noriskIgnore all risk properties (in scheduler mode)
-itt,--ignore-time-trackingIgnore all time sheet entries (in scheduler mode)
-ttp,--time-tracking-project project-idFilter out all time sheet entries for projects other than project-id
-ktcp,--keep-task-clock-propertiesRe-export task clock properties
note_s
without this switch, task clock properties will be exported as resource clock properties
-docs,--docsInterpret node text as markdown and append to (HTML) output (via app:md)
-dnf,--docs-no-footerSkip footer (TOC, foot notes, w3c validator)
-pt,--plain-todo
Convert plain todo.txt or minimal todo.org file to HTML or markdown report.
  • auto-create default resource
  • set allocate-default to default (#+allocate-default: default)
  • set effort-default to 1h (#+effort-default: 1h, -sde)
  • auto fold task groups (-afg)
  • skip gantt charts (-ssg)
  • show task titles instead of ids (-stt)
  • derive traffic lights from task state (-stls)
  • derive (default) document title from filename

5 Main file formats

5.1 Org / todo.txt (.org, .txt)

.org files can be converted to:
  1. Org or todo.txt (.org, .txt)
  2. Markdown (.md)
    • can then be converted to HTML, e.g. via app:md
      • HTML can then be imported into Word or LibreOffice (.docx)
  3. SimpleMind Pro Mindmap (.smmx)
  4. Comma-separated-value lists (.csv)
    • can be opened in Microsoft Excel or LibreOffice Calc
  5. HTML (.html)
    • can be imported into Microsoft Word or LibreOffice Writer
Supported encodings:

5.1.1 Structured text files

.org files are structured text files. In their simplest form, they can look like a todo.txt file:
- bread 
- butter 
- milk 
shopping_list.txt
an alternative way (which is used by the Emacs org-mode) to write this list looks like this:
* TODO bread 
* TODO butter 
* TODO milk 
shopping_list.org
Both examples define a document with three top-level TODO nodes.

5.1.2 Comments

Lines that commence with ; will be ignored by the parser and will not be exported to output files.
note_s
this is mostly useful for auto-generated files, e.g. for debug-info, or temporary, auto-calculated data (e.g. total efforts).
Please do not use this for regular comments (use a NOTE-type node instead).

5.1.3 Date formats

org recognizes the following date string styles:

5.1.4 General node syntax

The general node syntax looks like this:
Example:
* [<task_state>] [<tag_list>] [<priority>] node title [<effort>] [<progres>] [<tag_list>] 
 
e.g. 
 
* DONE :ui: [#B] implement icon button (3h) [4/4] 
** DONE add icon attributes to button 
** DONE load icon 
** DONE layout icon 
** DONE render icon 
Node layout (org-mode style)
<task_state_character> [<tag_list>] [<priority>] node title [<effort>] [<tag_list>] 
 
e.g. 
 
* DONE :ui: [#B] implement icon button (3h) [4/4] 
   + add icon attributes to button 
   + load icon 
   + layout icon 
   + render icon 
Node layout (mixed org-mode / todo.txt style)

5.1.5 Text lines

A node header can be followed by an arbitrary number of text lines. Each line will be trimmed and added to the current node.
Example:
* My Node 
  Some 
  arbitrary 
  text 
  lines. 
text_lines.org

5.1.5.1 Escaped text blocks via << .. >>

For text blocks containing markdown - or any other markup language - text, it may be necessary to enclose them in <<..>> tags.
Escaped text lines
Example:
* My Node 
  << 
  * This is an escaped text line 
   
  - this is a markdown list 
     - with a sub list 
      
  id: this will not be interpreted as a property assignment 
  >> 
escaped_text_blocks.org

5.1.6 Identifiers

Each node title is converted to a globally unique task id using the same mechanism that is used to create anchors in markdown text.
This means that
For example, the topic "My Topic Title" will be converted to the task id my-topic-title.
Since it is sometimes useful to override the auto-generated task id (usually when it's a sub-task), the id can be set via the
task_id or resource_id properties, or the simplified id or resource properties:
* Org Spec 
   ; auto-generated id, 'org-spec' 
 
* Test 
   id: org-test 
 
* Release 
   :PROPERTIES: 
   :task_id: org-release 
   :END: 
    
    
* Staff 
   * Tom 
      ; auto-generated id, 'tom' 
      resource 
 
* Peter 
      resource: ppa 
 
   * Paul 
      id: pkr 
      resource 
 
   * Mary 
      :PROPERTIES: 
      :resource_id: msh 
      :END: 
       
identifiers.org

5.1.6.1 Project id

The project id is derived from the anchorfied project title.
For example, if the project title is "My Test Project", the anchorfied project id will be "my-test-project".
The project id is used for time sheet entries (see Time Tracking).

5.1.7 States

Each document node can be assigned a task state. org supports the following states:
StateOrg KeywordShort FormDescription
<none><none>.Undefined state. Often used for task-groups / headers.
IDEAIDEA%An idea
NOTENOTE!A note. May contain hyper links.
TODOTODO-A pending task.
ACTVACTVoA task that is currently being worked on.
TESTTESTtA task that's almost been finished and is now being tested.
DONTDONTxA task that you thought about, but which you ultimately rejected.
IGNRIGNRXA canceled idea which did not make a lot of sense in the first place.
DONEDONE+A finished task.
QUESQUES?A topic that needs to be discussed.
WAITWAITwSome thing you're waiting for (which potentially blocks further progress).
Task states

5.1.7.1 Example

- bread 
+ butter 
- milk 
shopping_list_task_states.org
would therefore mean that you already bought "butter" (DONE) but still have to go out for bread and milk (TODO).

5.1.7.2 Example (SW)

5.1.7.2.1 simplified todo.txt syntax
using the simplified todo.txt style syntax:
+ write spec 
o implementation [1/5] 
   ; implementation is still work-in-progress 
   + feature 1 
      ; feature 1 is done 
   t feature 2 
      ; feature 2 is currently in testing 
   w wait for 3rd party supplier to send us that new lib 
   - feature 3 
      ! uses 'that new lib' 
   ? feature 4 
      ? do we really need this ? 
   x feature 5 
      ! scrapped. will implement feature 3 instead. 
- write documentation 
   ; why write documentation when more code could be written instead :-) 
% insert great idea for new feature here 
sw_task_states_todo.org
5.1.7.2.2 org-mode syntax
the equivalent file using the org-mode syntax:
* DONE write spec 
 
* ACTV implementation [1/5] 
   ; implementation is still work-in-progress 
    
** DONE feature 1 
    ; feature 1 is done 
     
** TEST feature 2 
    ; feature 2 is currently in testing 
     
** WAIT wait for 3rd party supplier to send us that new lib 
 
** TODO feature 3 
*** NOTE uses 'that new lib' 
 
** QUES feature 4 
*** QUES do we really need this ? 
 
** DONT feature 5 
*** NOTE scrapped. will implement feature 3 instead. 
 
* TODO write documentation 
   ; why write documentation when more code could be written instead :-) 
    
* IDEA insert great idea for new feature here 
sw_task_states_orgmode.org
5.1.7.2.3 todo / org-mode mixed syntax
the equivalent file using a mixed todo/org-mode syntax:
* DONE write spec 
 
* ACTV implementation [1/5] 
   ; implementation is still work-in-progress 
    
** DONE feature 1 
    ; feature 1 is done 
     
** TEST feature 2 
    ; feature 2 is currently in testing 
     
** WAIT wait for 3rd party supplier to send us that new lib 
 
** TODO feature 3 
    ! uses 'that new lib' 
     
** QUES feature 4 
    ? do we really need this ? 
     
** DONT feature 5 
    ! scrapped. will implement feature 3 instead. 
     
* TODO write documentation 
   ; why write documentation when more code could be written instead :-) 
    
* IDEA insert great idea for new feature here 
note_s
personally I prefer to use the org-mode syntax for top-level nodes, up to a nesting depth of 2 or maybe 3, then continue with the simplified todo.txt style syntax for the details

5.1.8 Priorities

Each document node can be assigned a priority, ranging from A (highest) to C (lowest):
- [#A] bread 
- [#B] butter 
- [#C] milk 
shopping_list_priorities.org
tip_s
Assigning priority [#A] to tasks which have to be done next makes it easy to find them

5.1.9 Tags

Each document node can be assigned an arbitrary list of tags:
- :bakery: [#A] bread 
- :farmersmarket: [#B] butter 
- :supermarket: [#C] milk 
shopping_list_tags.org

5.1.9.1 org-mode style tags

Tags may occur
- [#A] bread    :bakery: 
- [#B] butter   :farmersmarket: 
- [#C] milk     :supermarket: 
shopping_list_orgmode_tags.org
tip_s
The -tf,—tagsfirst command line option can be used to force placement of the tags before the topic/task title when an .org file is created.

5.1.9.2 Tags without start colon

When the tag list appears before the node title, the first colon can be skipped:
- bakery:        bread 
- farmersmarket: butter 
- supermarket:   milk 
tags_without_start_colon.org
note_s
this implicates that the node title must not contain : characters.
note_s
the command line switch -tarsc,--tags-always-requires-start-colon disables support for this tag-list style

5.1.9.3 Hash Tags

Tags may also be assigned via hash tags:
- [#A] bread 
   #bakery 
- [#B] butter 
   #farmersmarket 
- [#C] milk 
   #supermarket 
shopping_list_hash_tags.org
note_s
while it is possible for hash tags to contain spaces, it is not recommended to do so

5.1.9.4 allowed-tags

The global property allowed-tags can be used to validate that a node only uses tags from a known list.
This is mostly useful for detecting typos and redundant tags (e.g. hw vs hardware or textureunit vs texture-unit).

5.1.10 Progress

When the node header contains a string of the form [x/y] or [n%], org automatically replaces it with the current progress by looking at the child node states.
In other words, it will look like this:
* My task group [1/4] 
   - subtask 1  
      - not started, yet 
   + subtask 2 
      ! already finished 
   o subtask 3 
      ! still work-in-progress 
   t subtask 4 
      ! currently in testing) 
   ! just a note 
   ? just a question 
   x canceled 
progress.org

5.1.10.1 Recursive progress calculation

When the parent task (-group) contains a property named cookie_data that is set to todo recursive, the progress calculation recursively iterates the entire child node tree.
Example:
* My task group [3/6] 
   :PROPERTIES: 
   :cookie_data: todo recursive 
   :END 
   - subtask 1  
      - not started, yet 
   + subtask 2 
      ! already finished 
      + subtask 2.1 
      + subtask 2.2 
   o subtask 3 
      ! still work-in-progress 
   t subtask 4 
      ! currently in testing) 
   ! just a note 
   ? just a question 
   x canceled 
progress_recursive.org
note_s
the (rather strangely named) cookie_data property stems from the Emacs org-mode format and is supported due to compatibility reasons
If you don't care about Emacs org-mode compatibility, the simplified recursive property can be used instead:
* My task group [3/6] 
   recursive 
   - subtask 1  
      - not started, yet 
   + subtask 2 
      ! already finished 
      + subtask 2.1 
      + subtask 2.2 
   o subtask 3 
      ! still work-in-progress 
   t subtask 4 
      ! currently in testing) 
   ! just a note 
   ? just a question 
   x canceled 
progress_recursive_simplified.org

5.1.11 Properties

Each document node can be assigned an arbitrary number of properties.

5.1.11.1 User-defined properties

While some properties have special meaning (reserved property names), nodes may contain arbitrary user-defined properties which will simply be passed on as-is during document conversions:
- bread 
  :PROPERTIES: 
  :energy: ~265 kcal per 100g 
  :END: 
   
- butter 
  :PROPERTIES: 
  :energy: ~717 kcal per 100g 
  :fat: ~81g per 100g 
  :END: 
   
- milk 
  :PROPERTIES: 
  :energy: ~42 kcal per 100g 
  :fat: ~1g per 100g 
  :END: 
user_defined_properties.org

5.1.11.2 Reserved properties

Some properties have special meaning:
5.1.11.2.1 Reserved scheduler properties
Property NameDescription
task_idset task id (default is anchorfied topic title)
resource_idset resource id (default is anchorfied topic title)
dependsSet task dependencies (comma separated list of task ids)
forAdd task to target task dependencies (comma separated list of target task ids) ("for milestones xyz..")
milestoneTag task as milestone
foldSum efforts and don't export child nodes as separate tasks
org-foldalias for 'fold'
privateSum efforts but don't export child nodes (when combined with -p,--private command line option)
org-privatealias for 'private'
ignoreIgnore child nodes entirely
org-ignorealias for 'ignore'
effortSet task effort (e.g. 8h, 1d, 2w, 3m, or 0.5y) (1d=8h, 1w=40h, 1m=160h, 1y=260d or 2080h)
effortriskSet task effort risk (e.g. 1.2 or 20%)
durationSet task duration (e.g. 4h, 1d, 2w, 3m, or 0.5y) (1d=24h, 1w=168h, 1m=720h, 1y=365d or 8760h)
durationriskSet task duration risk (e.g. 1.2 or 20%)
allocateAllocate resource(s) to a task
workinghoursSet resource working hours
no-public-holidaysExcludes a resource from all public holidays
vacationAdd resource period of unavailability (due to vacation), <startdate>
sicknessAdd resource period of unavailability (due to sickness)
other-projectAdd resource period of unavailability (due to other projects)
Reserved scheduler property names
5.1.11.2.2 Reserved org properties
The following properties are used (usually auto-generated) when converting from org to smmx:
Property NameDescription
org-separator-styleASCII-separator style. minus, equal, asterisk, underscore, plus, tilde, dot, hash, colon, circumflex, aright, aleft.
org-separator-captionASCII-separator caption (after separator chars)
org-layoutlist or top-down
org-prio1..3 ⇒ A..C
org-tagsnode tags
org-empty-line-after-node-hdrforce empty line after node header when converting back to .org
org-empty-line-after-nodeforce empty line after node when converting back to .org
startstart date (same as SCHEDULED: simplified property)
idtask or resource id
smmx-calendar-date-typecalendar date source (create, finish, scheduled, deadline)
cookie_datawhen set to recursive, enable recursive progress calculation (traverse child nodes)
(emacs org-mode compatibility. also see simplified recursive property below)
Reserved org property names
5.1.11.2.3 Reserved smmx mindmap properties
The following properties are used (usually auto-generated) when converting from .smmx to .org:
Property NameDescription
was-maintopic was free-floating node in mindmap
smmx-positionnode or callout coordinate
smmx-palettecolor palette
smmx-colorinfocolor selection
smmx-iconicon name
smmx-text-styletext style flags ('bius', bold italic, underline, strikethrough)
smmx-font-scalefont size (2.4 = 24pt)
smmx-listsub-tree uses list layout
smmx-list-mdsub-tree uses markdown list layout
smmx-hull-visiblenode grouping
smmx-collapsedcollapse child nodes
hideshortcut for smmx-collapsed
smmx-fill-colorrgb24 html-style fill color, e.g. #ccc
smmx-border-stylesbsNone, sbsHalfRound, sbsDropRoundRect, sbsRoundRect
smmx-border-widthborder width
smmx-stroke-stylesolid, dash-s, dash-m, dash-l
smmx-stroke-colorrgb24 html-style fill color, e.g. #ccc
smmx-embedded-image-nameimage embedded in topic box
smmx-embedded-image-scalescaling factor (1.0=unscaled)
smmx-image-namecallout image or external image preview thumbnail
smmx-image-thumbnailcallout image preview thumbnail
smmx-image-urlexternal image URL
smmx-relationrelation (with target node)
smmx-parent-relationrelation (with parent node)
Reserved scheduler property names
5.1.11.2.4 Simplified properties
The following simplified properties can be set without using the :PROPERTIES: syntax:
Property NameDescription
idSet task or resource id (default is anchorfied topic title)
resourceTag node as resource (with optional resource id when followed by ':')
forAdd task to target task dependencies (comma separated list of target task ids) ("for milestones xyz..")
dependsSet task dependencies (comma separated list of task ids)
milestoneTag task as milestone
recursiveEnable recursive progress calculation (traverse child nodes)
scheduledSet start date (standard org-mode property)
deadlineSet deadline date (parsed but currently unused. this is a standard org-mode property)
createdSet the date when a task was first added
finishedSet the date when a task was completed (scheduler then ignores the task if it's before the start-date)
foldSum efforts and don't export child nodes as separate tasks
privateSum efforts but don't export child nodes (when combined with -p,--private command line option)
ignoreIgnore child nodes entirely
effortSet task effort (e.g. 8h, 1d, 2w, 3m, or 0.5y) (1d=8h, 1w=40h, 1m=160h, 1y=260d or 2080h)
effortriskSet task effort risk (e.g. 1.2 or 20%)
durationSet task duration (e.g. 4h, 1d, 2w, 3m, or 0.5y) (1d=24h, 1w=168h, 1m=720h, 1y=365d or 8760h)
durationriskSet task duration risk (e.g. 1.2 or 20%)
allocateAllocate resource(s) to a task
workinghoursSet resource working hours
no-public-holidaysExcludes a resource from all public holidays
vacationAdd resource period of unavailability (due to vacation)
sicknessAdd resource period of unavailability (due to sickness)
other-projectAdd resource period of unavailability (due to other projects)
clockAdd time sheet entry
Simplified properties
5.1.11.2.4.1 Example
* ACTV write documentation 
          id: org_docs 
    allocate: me  
      effort: 2d 
        risk: 50% 
   scheduled: <2020-01-22 Wed> 
    
* me 
   resource 
   workinghours: mo-fr 19-22, sat-sun 10:00-17:00 
   vacation: <2020-07-03 Fri> - <2020-08-09 Sun> 
     ; if only 
simplified_properties.org

5.1.12 Global Properties

Lines starting with #+ are interpreted as global properties.
For example, the document title and project start date can be set via
#+title:      My Project 
#+start-date: 23Jan2020 
The following global properties are supported:
Global Property NameDescription
titledocument title
start-dateproject start date (for scheduler)
todoorg-mode todo state configuration
note:
The default todo state is
#+TODO: IDEA TODO ACTV TEST DONT IGNR NOTE QUES WAIT | DONE 
It will automatically be prepended to each exported .org file.
allowed-tagscomma separated list of allowed tags
schedule-tagscomma separated list of tags displayed in scheduler output
startupemacs startup-options (e.g. showeverything, showall)
smmx-style-keyMindmap graphics style, e.g. system.colors-on-black-palette, system.gray-scale
smmx-info-positionposition of info node
smmx-root-positionposition of root node
Global property names

5.1.12.1 Simplified Global Properties

For reasons of convenience, the following simplified global property names are supported as well:
Simplified Global Property NameDescription
titledocument title
start-dateproject start date (for scheduler)
allowed-tagscomma separated list of allowed tags
schedule-tagscomma separated list of tags displayed in scheduler output
public-holidayadd public holiday (vacation time for all resources), <date>
Simplified global properties

5.1.13 Directives

5.1.13.1 Include files

The #+include: directive can be used to insert other (text-)files at any point in the document:
     title: test project 
start-date: <2020-02-03 Mon> 
 
#+include: staff.org 
 
- First task (1d) 
   allocate: peter 
   #+include: first_task.org 
    
- Second task (2d) 
   allocate: paul 
   #+include: second_task.org 
 
- Third task (5d) 
   allocate: mary 
   #+include: third_task.org 
note_l
Each line of an included file will be indentend by the number of spaces before the #+include directive.

5.1.13.2 Default resource allocation

The #+allocate-default: directive can be used to set the default task resource allocation:
#+allocate-default: me 
 
* me 
  resource 
   
* Task 1 (1d) 
* Task 2 (4d) 
allocate_default.org

5.1.13.3 Default effort

The #+effort-default: directive can be used to set the default task effort:
#+effort-default: 2d 
 
* Task 1 
* Task 2 
effort_default.org
note_s
this is mostly useful during the early stages of a project when a work breakdown structure starts to form but efforts have not been estimated, yet
Links in the body of a node (i.e. in the text lines that directly follow the node header) are not parsed at all (they are passed on as-is).
However, if the first child node of a node is an info note, the parser will check if the info topic is a link, and if it is, attach it to the parent mindmap node during .smmx conversion.
However (again), if a node contains several (successive) child nodes whose topics can be converted to links, these will be treated as a link list, and the first child node link will not be attached to the parent node.
It's probably easier to understand by looking at the following examples:
* Build flux capacitor 
   ! see https://example.com/research_note.html 
Single link (will be attached to parent node)
* A list of rather useless web sites 
   ! http://www.rrrgggbbb.com 
   ! http://endless.horse 
   ! http://ihasabucket.com 
   ! https://pointerpointer.com 
   ! http://chihuahuaspin.com 
   ! http://www.blankwindows.com 
   ! http://www.hackertyper.com 
   ! http://notdayoftheweek.com 
   ! http://pixelsfighting.com 
   ! http://buildshruggie.com 
Link list (will not be attached to parent node)
The following link formats are recognized by the org parser:

5.1.14.2 Automatic file suffix replacement

When converting between .smmx and .org files, the suffixes of linked files will automatically replaced.
I.e. when converting to .org, .smmx file suffixes will be replaced by .org, and vice versa.

5.1.15 Text Callouts

Text callouts are used to store short and comprehensive descriptions of the node's topic.
* My topic 
  > This is a brief description of my topic. 
  > This is the second line of the description. 
text_callout.org
note_s
Multiple text callouts will be interpreted as separate lines of a single multi-line callout.
tip_s
When an .org file is converted to an .smmx mind map, text callouts become actual callout boxes (e.g. speech bubbles).
tip_s
When an .org file is converted to a .csv or .html project plan, text callouts will be converted to comment fields.

5.2 SimpleMind Pro Mindmap (.smmx)

SimpleMind Pro is a (very affordable) mind mapping tool that is available for Windows, Mac, iOS, and Android.
org supports lossless conversion between text files and mind maps, in both directions.
Meta data not supported by the .smmx mindmap format will be stored as a mindmap note that is encoded in org format,
while meta data that is not supported by the .org format will be stored as smmx- properties.
.smmx files can be converted to:
  1. Org or todo.txt (.org, .txt)
  2. Markdown (.md)
    • can then be converted to HTML via app:md
      • HTML can then be imported into Word or LibreOffice (.docx)
  3. SimpleMind Pro Mindmap (.smmx)

5.2.1 Why mindmaps

Mind-mapping is a useful technique for brainstorming structured ideas or document outlines, favoured especially by visual thinkers.
org's ability to transform mindmaps into structured text documents (for further editing), and even back to mindmaps (for adding new ideas) makes these two a very useful combination for editing documents on both desktop on mobile platforms (like tablets and smartphones).

5.2.2 Conversion features

org supports all mindmap features including

5.2.3 Images

The .smmx files used by SimpleMind Pro are basically .zip files that store XML and PNG data.
When converting to .org, images will automatically be extracted from the mindmap and stored in the local files system (relative to the .org output file).
If a sub-directory named images/ exists in the output path, images will be placed there. Otherwise they will be stored in the same directory as the .org output file.
Vice versa, when an .org file is converted to .smmx, PNG images will be copied from the local file system to the .smmx archive.

6 Scheduler

The scheduler is enabled via the -s,—schedule command line switch.
Prerequisites:

6.1 Output formats

The scheduler can produce the following output formats:
suffixNameDescription
ConsoleConsole debug output (-d command line option)
.mdMarkdownMarkdown tables
.csvExcelExcel comma-separated-value lists
tip_s
Can be converted to simple Gantt graphs via the sim_city.xlsx template file.
.htmlHTMLHTML tables with Gantt graph(s)
tip_s
The Gantt graph can be disabled with the -ssg,—schedule-skip-gantt command line option
tip_s
The displayed tags can be limited via the schedule-tags global property
Scheduler output formats

6.1.1 Example

$ tks app:org -s myproject.org -o myproject.html 

6.1.2 Custom CSS files

When a CSS file with the same name as the input or output file but with suffix .css exists in the input or output directory, it will override the built-in style sheet.
$ tks app:org -s org_in/myproject.org -o html_out/myproject.html 
will look for CSS files org_in/myproject.css, html_out/myproject.css, and html_plan.css (in current working directory).
note_s
the CSS file content will be copied into the generated HTML document

6.2 Resources

Each task that is supposed to be included in a schedule needs to be assigned an effort, and a resource.
Resource are defined by via the resource / resource_id property:
* Peter Parker 
   ; Peter becomes a resource with the id 'peter-parker' 
   resource 
 
* Paul 
   ; Paul becomes a resource with the id 'pkr' 
   id: pkr 
   resource 
 
* Mary 
   ; Mary becomes a resource with the id 'msh' 
   resource: msh 
 
* Bruce 
   ; Bruce becomes a resource with the id 'batman' 
   :PROPERTIES: 
   :resource_id: batman 
   :END 
Resource definitions

6.2.1 Multiple resource assignments

When multiple resources are assigned to a task, the scheduler will try to utilize all of them but if a resource is blocked or vacant, it may only utilize some of the resources.
tip_s
It is always better to assign only one resource to a task and split larger tasks into sub-tasks when necessary

6.3 Working hours

Each resource can be limited to a certain set of days and hours via the workinghours property.
org recognizes the following string styles:

6.4 Example

* Peter 
   resource 
   workinghours: mo-thu 8:00-16:30, fri off 
Working hours

6.4.1 Out of Office periods

The scheduler will not assign resources during out of office periods. This includes vacations, public holidays, sickness, and other projects.

6.4.1.1 Vacation

The vacation property can be used to add one or many holidays to a resource.
It may occur multiple times.
* Peter 
   resource 
   vacation: <2020-01-28 Tue> - <2020-02-14 Fri> 
   vacation: <2020-07-09 Thu> - <2020-07-10 Fri> 
Vacations
6.4.1.1.1 Public holidays
The public-holiday global property can be used to define vacation periods for all resources.
It may occur multiple times.
; x-mas 
#+public-holiday: <2020-12-25 Fri> - <2020-12-26 Sat> 
 
* Peter 
   resource 
    
* Paul 
   resource 
    
* Mary 
   resource 
Public holidays
6.4.1.1.1.1 no-public-holidays
The no-public-holidays property can be used to exclude a resource from all public holidays (by default).
Please use the vacation or other-project property to re-add any subset of the globally defined public holidays.
#+public-holiday: <2020-12-25 Fri> - <2020-12-26 Sat> 
 
* Peter 
   resource 
   ; Peter is on holiday on the first day of x-mas but has to work on the second one 
   no-public-holidays 
   vacation: <2020-20-25> 
Working on a public holiday

6.4.1.2 Sickness

The sickness property can be used to exclude a resource from being allocated within the given period.
It may occur multiple times.
* Paul 
   resource 
   sickness: 27.01.2020 
Sick day

6.4.1.3 Other projects

The other-project property can be used to exclude a resource from being allocated within the given period (because (s)he's busy with other projects).
It may occur multiple times.
* Mary 
   resource 
   other-project: <2020-05-25 Mon> - <2020-05-29 Fri> 
Other projects

6.5 Task dependencies

6.5.1 Parallel sub tasks

A task always depends on its child- / sub tasks:
* Vacation 
   - Book hotel 
   - Pack suitcase 
   - Apply for a passport 
Parallel sub task dependencies
note_s
Sub tasks on the same nesting level are considered parallel tasks by default.
Parallel tasks can be assigned to different resources who can then work on them simultaneously.

6.5.2 Serial sub tasks

The ordered property is used to declare that all (direct) sub tasks have to be finished in the order of appearance:
     title: Ordered Schedule 
start-date: <2020-02-03 Mon> 
 
#+include: staff.org 
 
* Build a house 
   ordered 
   - buy property (1d) 
      allocate: peter 
   - foundation (2d) 
      allocate: paul 
   - rough framing (3d) 
      allocate: mary 
   - plumbing (4d) 
      allocate: paul 
   - electrical installation (5d) 
      allocate: mary 
   - insulation 
      ; the following two tasks can be done in parallel 
      - insulate walls (3d) 
         allocate: peter 
      - insulate roof (3d) 
         allocate: mary 
   - finish interior (7d) 
      allocate: paul 
 
* Milestones 
 
** Move in 
   milestone 
   depends: build-a-house 
Serial (ordered) sub task dependencies
This results in the following schedule:
TaskEffort (h)AllocateStartEnd
buy property8peter17.02.202018.02.2020
foundation16paul18.02.202019.02.2020
rough framing24mary20.02.202025.02.2020
plumbing32paul16.03.202019.03.2020
electrical installation40mary23.03.202031.03.2020
insulate walls24peter01.04.202007.04.2020
insulate roof24mary02.04.202007.04.2020
finish interior56paul07.04.202015.04.2020
Move in15.04.202015.04.2020
Ordered schedule output (considering vacations and part-time working hours)

6.5.3 Explicit dependencies

6.5.3.1 depends

The depends property can be used to define dependencies to any other tasks:
* Wood 
   - cut down another tree 
* Nails 
   - go to the hardware store 
* Rope 
   - plait some straw 
* Tree House 
   depends: wood, nails, rope 
Explicit task dependencies (depends)
caution_s
The dependencies apply to the current node only. If all sub-tasks shall depend on the given task(s), the after property must be used instead.

6.5.3.2 for

The for property can be used to add the current task to the list of dependencies of another task:
* Wood 
   for: tree-house 
   - cut down another tree 
* Nails 
   for: tree-house 
   - go to the hardware store 
* Rope 
   for: tree-house 
   - plait some straw 
* Tree House 
Explicit task dependencies (for)

6.5.3.3 after (inherit)

The after property is used to specify the dependencies for the current node (task), and also inherit them to all sub-tasks:
* Spec (1d) 
 
* Implementation 
  after: spec 
  fold 
 
  - module 1 (3d) 
  - module 2 (5d) 
Inherited task dependencies (after)

6.6 Task start and end dates

Each task is assigned a start and end date.
The start date is set when the first resource starts working on the task (or is planned to do so).
The end date is set
note_s
The finished property must be set for all tasks which have been completed before the project even started

6.6.1 Early task starts

As soon as a resource starts working on a task (which may even depend on another task that has not been completed, yet),
the task start date will be pushed forward.
However, the task will remain idle until its scheduled start date, i.e. the scheduler will not consume any further resource work hours until the scheduled date.

6.7 Milestones

The scheduler requires at least one milestone. It will then look at all the dependent tasks to generate the schedule.
; assign all following tasks to Peter 
allocate-default: peter 
 
* Peter 
   resource 
 
* Soup (1h) 
 
* Main Course (2h) 
 
* Dessert (0.5) 
 
* Supper 
   milestone 
   depends: soup, main-course, dessert 
Milestone example
Please take a look at the sim_city.org example project for a more comprehensive example.
tip_l
Tasks that were already finished before the project start-date will be ignored by the scheduler

6.8 Folding

In order to keep the total number of tasks within a reasonable limit, micro-tasks can be folded into a parent task via the fold keyword:
* Task 1 
   ; the 'fold' keyword will make the effort of this task the sum of all sub-tasks 
   ; i.e. "task-1" will require a total effort of (0.5+1+3+2) = 6.5h 
   fold 
   - micro sub-task1 (0.5h) 
   - micro sub-task2 (1h) 
   - micro sub-task3 (3h) 
   - micro sub-task4 (2h) 
fold_micro_tasks.org
note_s
time sheet entries must reference the parent task, no the the sub-tasks

6.8.1 private

The private keyword works similar to the fold keyword except that when the .org file is exported to a new .org file, private tasks will not be written to the new file when the -p,--private command line option is used.

6.8.2 ignore

The ignore keyword will cause all sub-tasks to be ignored during scheduling.
tip_s
a similar effect can be achieved by placing the sub-tasks in a sub-node that does not have a work state (TODO, ACTV, TEST, DONE)

7 Time Tracking

Without tracking the actual hours spent on each task, the scheduler can only assume an ideal / theoretical resource availability.
In reality, resources often work on multiple projects at once, or get side-tracked by unforseen tasks.
Time tracking can (and should) be used to document the actual number of daily working hours spent on each task.
(todo) implement+document privacy features (strip comments, list other project tasks as "other"), rewrite/filter time sheets to generate public sheet from private data

7.1 Syntax

An arbitrary number of time sheet entries can be attached to each resource:
* Peter 
   resource 
 
   ; date specifies first day of the week (usually a monday) 
   week 27Jan2020: 
     timetracking.task-1  4 5 6 7   7   insert arbitrary comment here 
     timetracking.task-2  0 1 1 1   0 
     admin                2 0 0 0   0 
     support              2 3 1 0.5 1 
timetracking.org

7.1.1 week

A time sheet entry starts with the keyword week, followed by the date of the first day of the week (see Date Formats).
The following lines of the time sheet entry must be indented, i.e. when the entry header starts with 3 spaces, the task lines must use an indent of 4 spaces or more.
Each task line starts with the project id, followed by a ., followed by the task id.
note_s
while the project id is actually optional (the current project id will automatically be filled in if it's missing), it is highly recommended to prefix all task ids with explicit project ids to avoid any ambiguities.
The remaining columns list the number of hours spent on each week day.
When a column is neither an integer or floating-point number, nor starts with - or x (aliases for 0), it is assumed to be a comment that terminates the task line.
tip_s
instead of a unique task-id it is also possible to use an path pattern that consists of anchorfied task titles, separated by . characters. Example:
module1.spec 

7.1.2 clock

Alternatively, daily time sheet entries can be entered as follows:
* Peter 
   resource 
    
   clock: timetracking.task-1  27Jan2020  4    insert arbitrary comment here 
   clock: admin                27Jan2020  2 
   clock: support              27Jan2020  2 
   clock: timetracking.task-1  28Jan2020  5 
   clock: timetracking.task-2  28Jan2020  1 
   clock: support              28Jan2020  3 
   clock: timetracking.task-1  29Jan2020  6 
   clock: timetracking.task-2  29Jan2020  1 
   clock: support              29Jan2020  1 
   clock: timetracking.task-1  30Jan2020  7 
   clock: timetracking.task-2  30Jan2020  1 
   clock: support              30Jan2020  0.5 
   clock: timetracking.task-1  31Jan2020  7 
   clock: support              31Jan2020  1 
timetracking_clock.org
note_s
This syntax is more suitable for auto-generated clock entries. It is used when re-exporting resources to org format.

7.1.3 Clock entries in task

Instead of listing the time tracked tasks in a resource definition, it is also possible to clock time within a task definition.
The prerequisite for this is that the task is allocated to exactly one resource.
* Peter 
   resource 
 
* Task 1 
   allocate: peter 
   clock: 27Jan2020 4h 
timetracking_per_task.org
note_s
by default, all clock entries (both resource and task) will be exported as resource properties
note_s
the -ktcp,--keep-task-clock-properties command line switch can be used to keep the clock entries in their original locations (i.e. in the task definition).
todo_s
support Emacs org-mode :LOGBOOK: entries

7.2 Now

When a project plan / agenda is generated, the scheduler compares project days to the actual current date (now).
When a project day (day 1 = project start) is in the past and there are no time sheet entries for that particular day and task, the scheduler assumes that zero working hours have been spent on the task.

7.2.1 Time sheet grace period

The -tsgp,--time-sheet-grace-period command line option controls how many days are allowed to pass until the scheduler assumes zero working hours instead of the ideal, maximum resource availability (according to the resource`s workinghours, vacation, and sickness properties).
note_s
The default setting is 10 days.

7.3 Privacy

The command line option -ttp,--time-tracking-project can be used to filter time sheet entries by a specific project-id.
Example:
$ tks app:org -psp -neh -ttp sim-city tests_org/private_resource.org -o out_org/public_resource.org 
Creating a public resource include file, filtered for the "sim-city" project
tip_s
Re-exported time sheet entries will always be stripped off their comments (which may contain additional working hour details)

8 Documentation

The -docs,--docs command line switch enables the document generator which interprets a node's text lines as markdown and converts them to HTML.
In scheduler mode, the resulting HTML document will be appended to the generated project plan.

note_s
The output format must be either HTML or markdown (output file name suffixes .html or .md).
caution_s
Generating HTML documents from .org via the --docs switch results in a different output than without the switch.
The default conversion creates a mind-map file first, converts that to .md, then to .html.
tip_s
The markdown-to-HTML conversion uses app:md, which supports many extensions not found in common markdown or GIT flavoured markdown.
tip_s
The inlined markdown text can include other pre-generated markdown or HTML content, or reference pre-generated documents and images.
It is recommended to use a Makefile (or similar build tool) to generated the content as required (i.e. to avoid redundant content generation).

Example:
tks app:org --docs tests_org/markdown_docs.org -o out_html/markdown_docs.html 
Generating .html documentation from .org file

9 Customizable HTML templates

When generating HTML documents, org uses a built-in template file (html_templates/builtin_template.html) by default.
This can be overridden via the -ht,--html-template command line option.
The following variables will be replaced in the template file:
VarDescription
$(TITLE)Document title
$(META)Additional meta tags (like auto-refresh)
$(CSS)Stylesheet data
$(PLAN)Project plan div
$(RV)Resource view div
$(DOCS)Documentation div
$(W3VALIDATOR)W3C validator icon+link (unless skipped via -dnf)
HTML template variables

10 License

org and md are distributed under terms of the MIT license.
Copyright 2020 bsp 
 
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 
 
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 

11 Downloads

The latest versions of org and md can be downloaded here:
note_s
org.tkx and md.tkx should be installed to the tks applications/ directory so they can be invoked via tks app:org and tks app:md

12 References


Valid HTML 4.01 Transitional

Document created on 09-Feb-2020 21:53:08