appendorgheading

This script appends [[https://orgmode.org][Org mode]] headings to any existing Org mode file which are plain text files with the extension =.org=.

You can use this script to generate arbitrary Org mode headings. It's mainly a wrapper script for the function =orgformat()= of [[https://github.com/novoid/orgformat][orgformat]].

** Why

The author is using this script to log things to an =errors.org= file which is part of his Org mode agenda:

: example_script.sh >out.log 2>&1 || : appendorgheading --output errors.org : --filecontent out.log : --level 2 : --keyword "TODO" : --title "example_script: some error occurred" : --daily

When this =example_script.sh= returns an [[http://tldp.org/LDP/abs/html/exit-status.html][exit status]] which is not zero, =appendorgheading= is adding a new heading to the file =errors.org= at level 2 (two asterisks) with the title "example_script: some error occurred".

Using the =--daily= parameter, there is a time-stamp attached which re-occurs on a daily basis. This looks similar to =<2019-12-29 Sun 16:01 +1d>= which causes this entry to appear on every agenda so that it gets recognized and hopefully resolved. On resolving the issue, the author deletes (or achives) this heading.

If these parameters are always the same, you can use the configuration file (see section below) to store the default values. Using this, you can reduce the example call above to:

: example_script.sh >out.log 2>&1 || appendorgheading

The =errors.org= gets a new heading that looks like:

: ** TODO example_script: some error occurred : : #+BEGIN_EXAMPLE : : #+END_EXAMPLE

Of course, there are much more command line parameters to add tags, priorities, and other Org mode heading properties. See section "Usage" below.

** Installation

This tool needs [[http://www.python.org/downloads/][Python 3 to be installed]].

You can install this script either via [[https://packaging.python.org/tutorials/installing-packages/][pip]] which is the recommended way. Or you can install it using the source code, e.g., by cloning the [[https://github.com/novoid/appendorgheading/][GitHub repository]].

Install via [[https://pip.pypa.io/en/stable/][pip]]: ~~pip install appendorgheading~~

** First Steps

After installing, I'd recommend you to read the help screen =appendorgheading -h= or the Usage section below in order to get an overview on the possibilities.

Then, you'd like to do generate a stub of a configuration file via: : appendorgheading --generateconfigfile testconfig.ini

Alternatively, you can use as many command line options as you like when generating the configuration file similar to: : appendorgheading --generateconfigfile testconfig.ini --output ~/org/errors.org --level 2 --daily

This will populate the generated configuration file with provided settings.

If you do like the generated configuration file, rename and move it to one of the two locations in order to activate the configuration file:

file =.appendorgheading= in the current working directory OR
in your home directory: =~/.appendorgheading=

Provided settings do have following priorities:

command line options
=.appendorgheading= in the current working directory
=~/.appendorgheading=

In other words: command line options always overrule any configuration file settings. Therefore, you can put your default settings in a configuration file and overrule via command line parameters whenever necessary to keep the average command line parameters at a minimum just as in the "Why" section.

If you are unsure, you can always use the test option =--dryrun= which doesn't change any files at all and tells you what would happen.

** Usage

#+BEGIN_SRC sh :results output :wrap src

./appendorgheading/init.py --help | sed 'sX/home/vkX$HOMEX'

#+END_SRC

#+begin_src usage: appendorgheading [-h] [--output <FILE.ORG>] [--level ] [--keyword ] [--priority "PRIO"] [--title "HEADING TITLE"] [--tags "STRING WITH TAGS"] [--scheduled "STRING WITH DATE/TIME-STAMP"] [--deadline "STRING WITH DATE/TIME-STAMP"] [--properties "KEY1:VALUE1; KEY2:VALUE2"] [--section "STRING"] [--filecontent ] [--daily] [--dryrun] [--generateconfigfile ] [-v] [-q] [--version]

This tool appends Org mode formatted headings to existing Org mode files.

The optional configuration file ".appendorgheading" can be placed:

the current directory ... OR ...
the home directory ("~/.appendorgheading")
Command line parameters override configuration file entries.

A typical use-case for this script is logging: The author is using this to log events to some kind of 'errors.org' which is part of his Org mode agenda.

example_script.sh >out.log 2>&1 || appendorgheading --filecontent "out.log"

This will use the default settings from your configuration file and log to the defined Org mode file only if "example_script.sh" has an exit status not equal to zero. It also appends the content of the log file for further analysis.

optional arguments: -h, --help show this help message and exit --output <FILE.ORG> Path to the Org mode file to append to --level The heading level (number of asterisks): 1, 2, 3, ... --keyword TODO keyword such as "TODO", "ERROR", ... --priority "PRIO" Priority indicator such as "A" or "C" --title "HEADING TITLE" Title of the heading --tags "STRING WITH TAGS" One or more tags (if multiple: in quotes, separated by spaces) --scheduled "STRING WITH DATE/TIME-STAMP" An Org mode date- or time-stamp such as "<2019-12-29 Sun>" which is added as SCHEDULED --deadline "STRING WITH DATE/TIME-STAMP" An Org mode date- or time-stamp such as "<2019-12-29 Sun>" which is added as DEADLINE --properties "KEY1:VALUE1; KEY2:VALUE2" A string with key-value pairs. Colons separate keys from values, semicolons separate the key-value-pairs. --section "STRING" This is used as the section text or body of the heading. --filecontent Path to a filename whose content gets appended to the section body within an EXAMPLE block --daily Add a time-stamp that is recurring on a daily basis --dryrun Enable dryrun mode: just simulate what would happen, do not modify files --generateconfigfile Path to a filename which gets created or overwritten with a configuration file that contains default values or the values given by the parameters -v, --verbose Enable verbose mode -q, --quiet Enable quiet mode --version Display version and exit

©️ (c) by Karl Voit [email protected] :license: GPL v3 or any later version :URL: https://github.com/novoid/appendorgheading :bugreports: via github or [email protected] :version: 2019-12-30 · #+end_src

** Examples

Additional to the example from the "Why"-section above, here are some other use-cases for this tool:

*** Checking for file age

Use-case: The author is generating an [[https://en.wikipedia.org/wiki/ICalendar][ical/ics-file]] via [[https://en.wikipedia.org/wiki/Cron][cron]]. If this is failing somehow because of Emacs tripping over some problematic Org mode data, this ics file gets old without noticing. Since I am using this to update [[https://radicale.org/][a calendar server]], this is a silent issue.

With =appendorgheading=, I can add a check for this using the shell script =appendorgheading-if-file-too-old.sh=:

#+BEGIN_SRC sh #!/bin/sh set -o errexit

FILENAME="${1}" MAXDAYS="${2}" HELPTEXT="${3}"

OLD=$(stat -c %Y "${FILENAME}") NOW=$(date +%s) DIFFDAYS=$(( ($NOW - $OLD) / (606024) )) DIFFHRS=$(( ($NOW - $OLD) / (60*60) ))

[ $DIFFDAYS -gt $MAXDAYS ] && /usr/local/bin/appendorgheading --title ""${FILENAME}" is older than $DIFFDAYS days" --quiet --section "File is $DIFFHRS hours old: $(ls -la "${FILENAME}")\n\n${HELPTEXT}" exit 0 #end #+END_SRC

My invocation command looks like:

: appendorgheading-if-file-too-old.sh /home/vk/.emacs.d/var/export/agenda-export.ics 0 "check with id:2019-11-19-HOWTO-check-and-fix-Org-agenda-radicale"

An example output in the resulting Org mode file could look like:

: *** "/home/vk/.emacs.d/var/export/agenda-export.ics" is older than 3 days : : <2020-06-02 Tue 10:57 +1d> : File is 75 hours old: -rw-r--r-- 1 vk vk 270538328 May 28 2020 agenda-export.ics : : check with id:2019-11-19-HOWTO-check-and-fix-Org-agenda-radicale

... which then finds its way to my agenda, reminding me to check this issue.

** Changelog

2019.12.30.1: first version
2020.06.02.1: added command line option for =--nodaily= to override configuration file preference

How to Thank Me

I'm glad you like my tools. If you want to support me:

Send old-fashioned postcard per snailmail - I love personal feedback!
- see [[http://tinyurl.com/j6w8hyo][my address]]
Send feature wishes or improvements as an issue on GitHub
Create issues on GitHub for bugs
Contribute merge requests for bug fixes
Check out my other cool [[https://github.com/novoid][projects on GitHub]]