Re: [RFC] Document level property drawer

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

Hi Adam,

Adam Porter <adam@alphapapa.net> writes:

> There are a lot of deprecation recommendations in your attached
> document:
> 
> > I propose to depricate property-keywords
> > I propose to depricate the Options-keyword
> > I propose to relabel these keywords as document keywords
> > I propose to depricate the #+CATEGORY syntax
> > I propose to depricate the #+FILETAGS syntax
> > I propose to depricate the #+COLUMNS syntax
> > I propose to depricate the #+ARCHIVE syntax
> > I propose to depricate the TODO-keywords
> > I propose to depricate the priorities-keyword
> > I propose to depricate the tags-keyword
> > I propose to depricate the link-keyword
> > I propose to depricate the constants-keyword
> > I propose to depricate the setupfile-keyword
> > I propose to depricate the Macro-keyword
> 
> The thoroughness of your investigation is admirable.

Thanks!

> However, I propose that we don't deprecate any of those.  Org has been
> around for over a decade now.  Such drastic changes would not serve
> users well.

I think you're right in the fact that Org mode will need to continue
to understand them. I'll say again that I wrote the document quite a
while ago. It's unedited and initially meant for my eyes only. So "to
deprecate" may be perceived to strong and I certainly didn't mean to
cut them out straight away. I don't think the diverse use of keywords
are good for the future of Org mode though, and I do think there is
value in trying to consolidate functionality and possibly promote
something that is more clear and easy to understand. Many of the
existing keywords have a corresponding property-syntax. For those I
think it would be good to start promoting using properties instead of
keywords (as I've written over and over again :) ). Other keywords
affect the Org mode configuration for the current buffer. They are
basically shortcuts to customization for the current buffer. Which led
me to proposing a settings drawer. It may be that it initially is
enough to just update the documentation with a chapter about keywords
and categorizing them in some groups based on intended purpose. I do
however still like the idea of collecting those keywords in a drawer
instead of having them spread out in the document.

> Note that I'm taking your use of the word "deprecate" to mean what
> it's expected to mean in this context: that the software developers
> recommend against using it, with the intention to eventually remove
> support for the feature.  We shouldn't be removing any such features
> from Org.
> 
> Not only would it not serve users well, but it would make the software
> much more complicated.  As it stands, finding, e.g. a #+CATEGORY:
> keyword and getting its value is as simple as:
> 
>     (save-excursion
>       (goto-char (point-min))
>       (when (re-search-forward (rx bol "#+CATEGORY:" (1+ blank)
>                                    (group (1+ nonl)))
>                                nil t)
>         (match-string 1)))
> 
> Hiding those keywords in drawers means that either:
> 
> a) Eligible drawers must be located, and then the desired
> property must be searched for inside of them.
> 
> b) Possibly valid properties must be located, and each one must be
> confirmed to be inside an eligible drawer.
> 
> What benefit would this added complexity serve?  To put the keywords
> in one place in the document?  There are already multiple ways to
> achieve that.

I don't agree here. Keywords today break the outline and have no
positional requirements. Both a property and a settings drawer would
have a fixed position to make it easy to locate, both programmatically,
visually and by search.

> I can't emphasize enough how important stability and consistency is
> for Org and its file formats right now.  As I've said, there are new
> implementations in development, which have the potential to bring a
> lot of publicity and new users to Org.  For example, this one was
> mentioned on a Hacker News post a few days ago:

There is always a balance between stability, backwards compatibility
and progression. I agree that backwards compatibility and stability is
important. But I also argue that progression is important. Good if Org
mode is gaining traction! But that doesn't mean we can't improve it
further, for it to gain even more traction! And in the larger scheme
of things, Org mode still is tiny. So let's not oversell ourselves
here. It's almost like a catch 22. But the largest hinderance for Org
mode to grow further is probably its ties with Emacs, the very thing
that makes Org mode into the powerhouse it is!

> https://github.com/mickael-kerjean/filestash
> 
> In the same HN post were examples of implementations for Vim and
> VSCode.  Already, especially in the VSCode ones, there were apparent
> incompatibilities in their implementations of the Org file format.

I've been a promoter of separating the Org mode syntax from Emacs for
a long time. I think I've written about it on this list previously as
well. So I know what you mean. That still isn't any argument for
stopping progress and improvement.

> As well, there are now parsers in JavaScript, Python, and Rust.
> 
> Markdown is by far the most popular plain-text format, and has been
> for years, but it has long suffered from competing, slightly
> incompatible flavors and implementations.  Reddit has theirs, GitHub
> has theirs, etc.
> 
> Org's file format may finally be gaining some momentum.  Let's not
> jeopardize Org's chances by making implementors' job more difficult
> than it already is.

I think that's a bit to defensive from Org mode's perspective. Yes, we
should promote other tools to start implementing Org mode parsers. No,
we shouldn't make it more difficult. But also let's not stop all
progress with the belief that it will make life easier. I believe that
a document property drawer that follows the syntax of the outline
drawer will make life easier for those you're talking about. Though in
the end it's always the end users we have to think most about.

I think your lobbying against this has had effect though, since the
property drawer already is out of 9.3 and in a separate branch.

Regards,
Gustav