doc: Replace README.md by README.org

Makefile

@@ -1,22 +1,27 @@
-.PHONY: default all install watch clean build release distclean lint
+.PHONY: default all install watch clean build release distclean lint doc
 default: all
 
 all: build
 
-build: builddir build/bin/annotator
-
 GHCFLAGS = -iapp -isrc -Wall -O2 -outputdir build/.obj
 BUILDDIR = build
 DESTDIR = ~/.local
 BINDIR = ${DESTDIR}/bin
 DOCDIR = ${DESTDIR}/share/doc/annotator
 
+build: builddir | $(BUILDDIR)/bin/annotator doc
+
 builddir:
-	mkdir -p $(BUILDDIR)/bin $(BUILDDIR)/.obj $(BUILDDIR)/ci $(BUILDDIR)/dist
+	mkdir -p $(BUILDDIR)/{bin,.obj,ci,dist,doc}
+
+doc: builddir | $(BUILDDIR)/doc/README.md
 
 $(BUILDDIR)/bin/annotator: app/Main.hs src/*.hs
 	ghc --make $(GHCFLAGS) $< -o $@
 
+$(BUILDDIR)/doc/README.md: README.org
+	pandoc -t gfm $< -o $@
+
 watch:
 	@git ls-files src app Makefile | entr make -s build install
 
@@ -31,9 +36,10 @@ clean:
 distclean: clean
 	@rm -rf dist
 
-install: $(BUILDDIR)/bin/annotator
+install: build
-	@install -m 0755 -D -t ${BINDIR} $<
+	@install -m 0755 -D -t ${BINDIR} $(BUILDDIR)/bin/annotator
-	@install -m 0644 -D -t ${DOCDIR} README.md
+	@install -m 0644 -D -t ${DOCDIR} README.org
+	@install -m 0644 -D -t ${DOCDIR} $(BUILDDIR)/doc/README.md
 
 release: script/make-release
 	@$<

README.md

@@ -1,84 +0,0 @@
-# Annotator - an interactive TM2/TM3 annotation tool
-
-This tool lets you interactively annotate your code given a =defects.err= file.
-
-## Installation
-
-Get the most recent release, unpack it and add the binary to your PATH.
-
-## How to use it
-
-After a /Coverity™/ run, you end up with a =defects.err= and would like to
-annotate your code accordingly. In order to do so, just execute the =annotator=:
-
-```
-annotator
-```
-
-This will by default use the =defects.err= file in the current directory and
-scan it for violations. It will then ask you what to do with each violation - by
-default only /Newest/ violations will be handled, but this can be overridden
-with a command-line switch.
-
-After all violations have been treated, you'll end up with a bunch of =*.fix=
-files next to each source file - those are the annotated source files - you may
-run diff on them to check if they look fine or just move them over your original
-source file.
-
-### Possible annotations
-
-The annotator is able to generate three kinds of annotations:
-
-  - *Intentional* - by pressing `i`, this will annotate with `coverity[rule] <reason>`
-  - *False-Positive* - by pressing `f`, this will annotate with `coverity[rule : FALSE] <reason>`
-  - *Todo* - by pressing `t`, this will annotate with a FIXME marker
-
-## Advanced usage scenarios
-
-The current annotator supports the following command-line arguments:
-
-```
-$ annotator --help
-Usage: annotator [OPTIONS] files...
-
-A tool to semi-automatically add Coverity source-code annotations based on found defects.
-
-
-  -v          --verbose               be more verbose, pass multiple times to increase verbosity
-  -i          --inplace               replace source-file after inserting annotations
-  -V          --version               show full version information
-              --short-version         show just the version number
-  -h          --help                  show usage information
-  -a          --all                   handle all defects not just Newest
-  -C[NUM]     --context[=NUM]         specify how much context should be shown around a violation
-  -t[STRING]  --todo-marker[=STRING]  override the default TODO marker with a custom string
-  -A FILE     --annotations=FILE      load automatic annotation rules
-```
-
-### In-place annotations
-
-The `annotator` allows to annotate in-place, i.e. it will automatically rename
-the `.fix` file after you are done with all violations within that file. This
-can be achieved by passing `-i` or `--inplace`.
-
-### Process all violations
-
-By default the annotator will only handle *Newest* violations and not those that
-are already contained within the Coverity database for some reason. However,
-it's still possible to process all found violations by passing `-a` or `--all`
-on the command-line.
-
-### Insert annotations automatically
-
-In case you have violations that always result in the same annotation over and
-over again, you can supply one or more files that contain automatic decisions.
-
-Each line may be one of the following:
-
-```
-Intentional (Rule "autosar_cpp14_a18_9_1") "reason why it's intentional"
-FalsePositive (Rule "autosar_cpp14_a18_9_1") "reason why it's a false-positive"
-ToDo (Rule "autosar_cpp14_a18_9_1")
-```
-
-Lines may be disabled by prefixing them with `#` or `--`.

README.org

@@ -1,14 +1,54 @@
-#+title: Readme
+#+title: Annotator - an interactive Coverity annotation tool
+
+* Abstract
+
+This tool lets you interactively annotate your code given a =defects.err= file. The file should contain file and line information along with the Coverity rule that was violated. An example may look like this:
+
+#+begin_example csv
+main.cpp:162:INFO: Newest, autosar_cpp14_a20_8_6_violation: Object "std::unique_ptr<Configuration const, std::default_delete<Configuration const> >(read_configuration(uri))" is not constructed using "std::make_shared".
+#+end_example
 
 * Installation
 
+Get the most recent release, unpack it and add the binary to your PATH.
+
 * Usage
 
-#+begin_src sh :results output
+After a /Coverity™/ run, you end up with a =defects.err= and would like to
+annotate your code accordingly. In order to do so, just execute the =annotator=:
+
+#+begin_src sh
+annotator
+#+end_src
+
+This will by default use the =defects.err= file in the current directory and
+scan it for violations. It will then ask you what to do with each violation - by
+default only /Newest/ violations will be handled, but this can be overridden
+with a command-line switch.
+
+After all violations have been treated, you'll end up with a bunch of =*.fix=
+files next to each source file - those are the annotated source files - you may
+run diff on them to check if they look fine or just move them over your original
+source file.
+
+** Possible annotations
+
+The annotator is able to generate three kinds of annotations:
+
+- Intentional :: by pressing =i=, this will annotate with =coverity[rule] <reason>=
+- FalsePositive :: by pressing =f=, this will annotate with =coverity[rule : FALSE] <reason>=
+- Todo :: by pressing =t=, this will annotate with a TODO marker
+
+* Advanced usage scenarios
+
+The current annotator supports the following command-line arguments:
+
+#+name: annotator-help
+#+begin_src sh :results output :exports both
 annotator --help
 #+end_src
 
-#+RESULTS:
+#+RESULTS: annotator-help
 #+begin_example
 Usage: annotator [OPTIONS] files...
 
@@ -32,3 +72,25 @@ A tool to semi-automatically add Coverity source-code annotations based on found
                                         # a comment
                                         -- another comment
 #+end_example
+
+** In-place annotations
+
+The =annotator= allows to annotate in-place, i.e. it will automatically rename the =.fix= file after you are done with all violations within that file. This can be achieved by passing =-i= or =--inplace=.
+
+** Process all violations
+
+By default the annotator will only handle *Newest* violations and not those that are already contained within the Coverity database for some reason. However, it's still possible to process all found violations by passing =-a= or =--all= on the command-line.
+
+** Insert annotations automatically
+
+In case you have violations that always result in the same annotation over and over again, you can supply one or more files that contain automatic decisions.
+
+Each line may be one of the following:
+
+#+begin_example haskell
+Intentional (Rule "autosar_cpp14_a18_9_1") "reason why it's intentional"
+FalsePositive (Rule "autosar_cpp14_a18_9_1") "reason why it's a false-positive"
+ToDo (Rule "autosar_cpp14_a18_9_1")
+#+end_example
+
+Lines may be disabled by prefixing them with =#= or =--=.