Re: [RFC] Document level property drawer

[Adam Porter <adam@alphapapa.net>]

Hi Gustav,

Gustav Wikström <gustav@whil.se> writes:

> I'd argue that precedence already works that way. One has to take
> inheritance into account. With inheritance turned on, tell me which
> value for Property1 is used for the nodes in the following example:
>
> #+begin_src org
>   ,* Node 1
>   ,* Node 2
>   :PROPERTIES:
>   :Property1: Value1
>   :END:
>
>   ,#+PROPERTY: Property1 Value2
> #+end_src
>
> As you'll see line number already isn't the deciding factor.
>
> With two ways to define properties it makes sense to first think of
> which syntax to promote as "more important" and then to think of
> precedence rules for duplicates within each syntax.
>
> Having the same syntax for node level 0 as for regular nodes makes the
> property functionality easy to understand and congruent. Something I
> think is worth promoting by saying that property blocks on file-level
> has precedence over the keyword syntax.

I think this example illustrates the issue better.  This is how Org
currently works:

#+BEGIN_SRC org
  # Category here is "Alpha"

  ,* Node 1

  # Category here is "Alpha"

  ,* Node 2
  :PROPERTIES:
  :CATEGORY: Beta
  :END:

  # Category here is "Beta"

  ,#+CATEGORY: Alpha
#+END_SRC

IIUC, your proposal would work like this:

#+BEGIN_SRC org
  :PROPERTIES:
  :CATEGORY: Gamma
  :END:
  
  # Category here is "Gamma"

  ,* Node 1

  # Category here is "Gamma"

  ,* Node 2
  :PROPERTIES:
  :CATEGORY: Beta
  :END:

  # Category here is "Beta"

  ,#+CATEGORY: Alpha
#+END_SRC

So the #+CATEGORY: line has no effect because of the first-line property
drawer.

In Org, some keywords are special, like #+CATEGORY.  For many years,
such keywords have had file-wide effects regardless of their placement
in the file.  IIUC, your proposal would change that, and that would
still be a major, breaking change.

> If you think of the document as an outline, something Org mode is all
> about, it makes sense to also think of things before the first
> headline as "node level 0". And with that way of conceptually thinking
> of the document it makes perfect sense to have a property drawer fixed
> at the top - in the same way as it is required for all other node
> levels.

What you're proposing is actually a fundamental change to the way Org
documents are interpreted.  Org documents are not currently an outline,
just a series of elements which may include an outline.  Text and
elements before a first heading are not part of a node, they're just
text and elements in the document.

If Org were a new project, I think your proposal might be very
suitable.  But at this point, it would be a significant, breaking
change, even without the org-element parser changes.

Consider as well that the Org format has recently been seeing wider use,
with more implementations becoming available in several languages and on
several platforms.  Fundamental changes like this would affect more than
just the official Org software, and the costs of breaking software in
the wider Org community should be carefully considered.