________________________________________
PROPOSAL FOR NEW DOCUMENT-LEVEL SYNTAX
Gustav Wikström
________________________________________
Table of Contents
_________________
1. Summary
2. Background, details etc.
3. Proposal details
4. Code?
1 Summary
=========
I propose a "document" element in org-element, a property-drawer on
document-level, a setting-drawer on document-level and
property-keywords (slightly different than what already exist). And
would like your comments regarding that!
More details below.
2 Background, details etc.
==========================
I'm amazed by how well org-mode fullfills my needs for writing,
thinking, organizing and structuring information. Having a text-based
outliner with rich formatting, searching and inter-linking options is
amazing! There are a few things that's bugged me for a while though.
One of those things is the fact that org-mode is lacking when you're
outside of a headline. Basically, org-mode lacks the proper notion of
a document. One use case for a more clear notion of a document is for
large libraries of short notes separated by files instead of separated
by headlines. Separating notes by files has drawbacks today. You can't
easily define todo's, tags, ID's, attachments etc. when your not
within a headline!
You might think: "But just create a headline if you want those
things..!"
To which I'd answer: "Yes, that works. As a workaround. But it's not
good enough! What do I name my headline? I already have a name for the
file, having to define a name again for a headline inside that file is
redundant for short notes."
Look for example at org-brain which had to introduce separate concepts
to be able to deal with files and subtrees ([headlines and files]).
Some org-brain issues that relates to this lack of a document-concept:
([#118], [#91], [#48]). This suggestion is not about org-brain. But I
just wanted to give an example of how this is something that /can/ be
improved.
To get started on this road towards a clearer definition and syntax
for things above the headline-concept, I have a couple of suggestions
I hope the community will support!
[headlines and files]
<https://github.com/Kungsgeten/org-brain#headline-and-file-entries>
[#118] <https://github.com/Kungsgeten/org-brain/issues/118>
[#91] <https://github.com/Kungsgeten/org-brain/issues/91>
[#48] <https://github.com/Kungsgeten/org-brain/issues/48>
3 Proposal details
==================
I propose to introduce two org-mode drawers to be used in the top of
org-mode documents:
1) A setting drawer. Applicable only if positioned at the top of a
buffer, below any potential comment-line or document-level keywords
(more on those later).
2) A property drawer. Applicable with the same positional condition as
the settings-block, and positioned after the settings-block if both
blocks are available.
I also propose to allow for whatever property to be defined as a
keyword if also defined at the top of the document.
Details for these proposals follows:
The setting drawer makes the following keywords redundant:
- #+STARTUP
- #+TODO
- #+SEQ_TODO
- #+TYP_TODO
- #+PRIORITIES
- #+TAGS
- #+LINK
- #+CONSTANTS
- #+SETUPFILE
- #+MACRO
Initially I propose to just use the setting drawer as an additional
syntax allowed for the above keywords, preferably with a new
helper-method for setting them. Settings defined in this drawer should
have precedence over settings defined by the keywords above. Long term
I'd like to depricate the above keywords in favour of the setting
drawer.
The property drawer is used for properties defined at node-level 0.
Properties defined inside this drawer are applied in exactly the same
way as properties on headline-entries are applied for it's subtree.
I.e. the same inheritance-rules apply.
The property drawer makes the following keywords redundant: (since all
of them have property drawer equivalences)
- #+PROPERTY
- #+OPTIONS
- #+CATEGORY
- #+FILETAGS
- #+COLUMNS
- #+ARCHIVE
Defining properties on the document-level should work using the same
commands as today when the point is before the first headline.
Properties defined in the document property drawer should have
precedence over properties defined by the (then redundant) keywords
above.
I propose to allow properties to be defined also as document property
keywords. All keywords in the top of a buffer, before any non-comment
line, are document-level keywords. In effect, they are properties that
apply in exactly the same way as properties defined in the property
drawer. The only reason for using a document keyword instead of
defining it inside the property drawer is to make it more visible. One
example would be the title-keword (#+TITLE: ...).
4 Code?
=======
Work in progress can be found here:
<https://github.com/Whil-/org-mode>
With separate branches in an attempt to isolate things from each
other:
New document element
<https://github.com/Whil-/org-mode/tree/feature/org-document-formalization>
Document property drawer
<https://github.com/Whil-/org-mode/tree/feature/org-document-property-drawer>
Document property keywords
<https://github.com/Whil-/org-mode/tree/feature/org-document-property-keywords>
Document setting drawer
<https://github.com/Whil-/org-mode/tree/feature/org-document-setting-drawer>
The first two branches are working already (though lacking
documentation) while the two last ones mostly exist as ideas. Note
that of these branches most likely will get their history rewritten
from time to time. I.e they're public... but dangerous!
