Re: [RFC] Document level property drawer

["Gustav Wikström" <gustav@whil.se>]

Hi Adam,

> How does it differ from what was previously proposed?

It differs by not introducing the document concept in Org element.
Removing that means there is no reason to wait for another major
version of Org mode.

> What exactly does "will (shall)" mean?

You can ignore the inside of the parentheses. It carries no important
meaning.

> > 3) Properties defined in a property drawer will have precedence over
> >    properties defined as a property keyword, if the same property is
> >    defined using both conventions.
> 
> That protocol seems unnatural and confusing to me:
> 
> - If precedence were to be defined by something other than file-order,
>   it seems to me that those defined with #+ keywords should have
>   precedence, because they are more visible, while those in drawers are
>   hidden.
> - However, it seems to me that the simplest, most natural protocol would
>   be for later declarations to override earlier ones.

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.

> > 4) The position for the document level property drawer is:
> >    - At the first line in a file that is not a comment or a keyword.
> >
> >      I.e. the following will work:
> >
> >      #+begin_src org
> >        # -*- mode: org -*-
> >        ,#+TITLE: Test
> >        :PROPERTIES:
> >        :CATEGORY: Test
> >        :END:
> >
> >        Preamble 
> >
> >        ,* Some heading
> >        Some content
> >      #+end_src
> >
> >
> >      but not this:
> >
> >      #+begin_src org
> >        Some comment and/or empty line
> >
> >        :PROPERTIES:
> >        :CATEGORY: Test
> >        :END:
> >
> >        ,* Some heading
> >        Some content
> >      #+end_src
> 
> That feels unintuitive to me.  Document-level property keywords may
> appear anywhere in a file, so it seems inconsistent for document-level
> property drawers to be limited in this way, as if there were an implied
> headline at the top of the file.  If it were so, I would expect to see
> many mailing list posts by users asking why the properties defined in
> their document-level property drawers aren't working.  Given that there
> is no enforcement in Org's UI to keep such drawers in certain places, I
> think the implementation should be tolerant of users' preferences and
> mistakes (cf. Postel's Law).

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.

Regarding the placement of drawers, if you apply my patch on your end
to test it out you'll see that the built in functionality to define
properties creates the drawer for you. That's easy to do since it's
positional rule is easy to derive by the system. Try for example
org-set-property (C-c C-x p) and you'll get the drawer defined for
you. In exactly the same way as it already works when you're inside a
heading today.

The lack of posts asking why properties defined on their outline nodes
doesn't work tells me that positional requirements for property
drawers already is well understood.

Kind regards
Gustav