The intention of this repository is to build up copius examples of org-mode snippets to be used for testing parsers of the grammar. Ideally, this would be a place for developers and users to share samples to demonstrate issues with whatever is being developed. As the collection grows, so would the set of examples available for testing hopefully improving the quality of tools built on top of org-mode.
I can envision a user using the collection to try to narrow down a buggy case and/or point a developer at an example to demonstrate an issue. Or, absent an existing case, creating one.
At the moment it isn’t very well organized. :^) Since this is envisioned to be a community effort, the hope is that the community will have the best ideas for how it should be organized. But I have a couple ideas.
For instance, the current spec for the org-mode grammar isn’t terribly precise at points. There
appear to be things like skipping a heading level which is tolerated by the org-element.el
parser, but seemingly not allowed according to the spec. I can imagine having a section of the
tests for pathalogical cases. I can also imagine a section specifically for say blocks.
You have to start somewhere! :^) I’ve tried to get the ball rolling and will add what I can think up, but for this to really be successful it’s going to need community input.
Let’s make this happen!
My first stab at this is to have a single file with multiple snippets in it to make editing
easier. Each snippet is separated by a null character (^@ in emacs). I then used the
following zsh to split that up into separate files in a folder of the same name.
$ c=0 $ cat headings.org | while read -d '' f; do printf "%s" "$f" > headings/$c.org; c=$((c+1)); done
If this proves a useful approach I’ll look to automate this.
There are! But what (barely) separates this from other projects is the explicit call for community involvement. Here are a few I know about but would love to hear of more.
Awesome!! Welcome aboard!!!
See Wiki for brainstorming ideas. Or maybe the Discussion section is better?
You can use emacs in batch mode to see the whole document AST as follows:
$ emacs v0.0/tags/5.org --batch --eval="(pp (org-element-parse-buffer))"
(org-data nil
(headline
(:raw-value "Heading" :begin 1 :end 36 :pre-blank 0 :contents-begin nil :contents-end nil :level 1 :priority nil :tags
("tag1" "ARCHIVE" "tag2")
:todo-keyword nil :todo-type nil :post-blank 0 :footnote-section-p nil :archivedp
("ARCHIVE" "tag2")
:commentedp nil :post-affiliated 1 :title
(#("Heading" 0 7
(:parent #1)))
:parent #0)))
$
Under /scripts, there is a simple elisp script which can be run in batch mode to print the
structure of an org document as emacs sees it. It can be run as follows:
$ emacs --batch v0.0/headings/12.org --eval="(require 'package)" --eval="(package-initialize)" --eval="(require 'dash)" -l $(pwd)/scripts/dumptree.el
(org-data
(section
(paragraph))
(headline
(section
(paragraph))
(headline
(section
(paragraph)))))
$
With a little more scripting foo, you can run it on a bunch of files:
$ seq 8 12 | while read num; do echo "== $num =="; emacs --batch v0.0/headings/$num.org --eval="(require 'package)" --eval="(package-initialize)" --eval="(require 'dash)" -l $(pwd)/scripts/dumptree.el; done
== 8 ==
(org-data
(headline
(section
(paragraph))
(headline)))
== 9 ==
(org-data
(section
(paragraph))
(headline
(section
(paragraph))
(headline)))
== 10 ==
(org-data
(headline
(headline
(section
(paragraph)))))
== 11 ==
(org-data
(headline
(headline
(section
(paragraph)))))
== 12 ==
(org-data
(section
(paragraph))
(headline
(section
(paragraph))
(headline
(section
(paragraph)))))
$