Re: [O] Proposal for new document-level syntax

[Gustav Wikström]

Hi again,

This became a bit long, so the most important thing is repeated here
in the top:

I think there is merit to the idea of a file/document/buffer being
seen as a level-0 node. I think we'd benefit by adhering to the
principles for outline nodes also for the document-node (level-0 node)
as much as possible.

I'd like the specification for org-mode to be clear and succinct and
it's features to be as congruent as possible.

Comments to your concerns and questions below!

> -----Original Message-----
> From: Nicolas Goaziou <address@hidden>
> Sent: den 3 juni 2019 22:40
> To: Gustav Wikström <address@hidden>
> Cc: address@hidden
> Subject: Re: Proposal for new document-level syntax
> 
> Hello,
> 
> Gustav Wikström <address@hidden> writes:
> 
> > No worries. I think I explained but it can be further detailed. What I
> > mean is that any property you can think of should be possible to add
> > to a document as a keyword with the syntax:
> >
> > #+{PROPERTY}: {Value}
> 
> IIRC, Org uses
> 
>   #+PROPERTY: {key} {value}
> 
> Why "should" it be possible to use a different syntax?

The main change I want to introduce is the property-drawer. The new
property-syntax is secondary but makes 100% sense when you start
thinking about it. If you read through my initial mail you'll see that
I'm trying to consolidate functionality, moving things from keywords
possibly scattered throughout a document into drawers. That
consolidation is to simplify org-mode, even though it for a while will
make the /actual implementation/ more complex to maintain backwards
compatability. There is a longer investigation behind this that I
probably should share. But given the already long text and what I
understand is a lack of time to read it I hesitate to wall-of-text you
guys more than I'm already doing! :) So I'm taking things
incrementally when questions arise!

To the point; the =#+{PROPERTY}: {Value}= syntax idea started with
thinking about the purpose of existing export keywords. [fn:1] They're
not /only/ valuable for exporting. Defining a title for a document
(TITLE is an export-keyword) makes sense even if you don't export a
document. And what is that title-keyword really? It's a property! You
can define it in an outline as well! [fn:2]

Thinking of TITLE as a property, and thinking of depricating the
export keywords (i.e. remove that concept but maintain functionality
with properties) lead to the problem of TITLE in the future being
hidden away in a drawer. Being a user of the short and easy syntax for
export keywords today, my idea was to generalize them to work for all
properties. But contain them to a fixed position above the document
property drawer since the only use of that kind of property-definition
is to visually highlight it while letting all other document
properties be hidden away in the drawer.

What I've done is to try to not get stuck in existing syntax and think
more freely what would benefit us long term. I hope you can appreciate
that. It will indeed create another way of defining properties on
document-level . But I claim it makes sense! And I claim that the
current way of defining document properties with the

  #+PROPERTY: {key} {value}

doesn't make that much sense when we have document property drawers in
place! I do appreciate the concern of making breaking changes, which
is the reason for not proposing the removal of existing document
property syntax. That maybe could be saved for a major version
sometime in the future, when the drawer has been tried and tested
more, and hopefully accepted more! (I honestly didn't think I'd get
resistance for trying to introduce it...)

> > But only at the beginning of a file, before any other content. The
> > only reason for defining properties like that is for them to be
> > visible outside of the property drawer. I'm thinking mostly of
> > =#+TITLE= and similar keywords.
> >
> > I'd like to depricate =#+PROPERTY:= since it breaks the outline
> > hierarchy and doens't follow the convention for how properties are
> > defined inside headlines.
> 
> So the reason for this change is that keywords break the outline
> hierarchy? Well, keywords do not belong to the outline hierarchy in the
> first place. But syntax is not very different, either.

No no no, you clearly have not read my first mail. Please do. Keywords
breaking the outline hierarchy is only one of the reasons. What you're
saying is actually exactly what I mean with them breaking the outline.
I'm just a bit harsher and more strict - If keywords don't belong to
the outline, then don't put them inside headlines in the outline! They
don't belong there! Also, as I'm sure you're aware since you are the
most knowledgable org-mode'er out there, the following keywords *do*
belong in the outline: 
  #+NAME 
  #+TOC 
  #+ASCII
  #+INCLUDE

What I'm saying is basically that all keywords that "break the
outline" (or in your words: don't belong to the outline hierarchy),
can - and should! - be put into drawers before the first headline.
That way we don't even have to argue about what it means to belong or
not belong to the outline. One can claim that they belong to level-0
in the outline or one could claim that they have nothing to do with
the outline. Both perspectives are fine.

> > Removing the "old" way of defining properties for the whole buffer
> > will make property-syntax defined the same for documents and
> > headlines. With the slight extention of allowing arbitrary keywords to
> > stand for properties at the beginning of the buffer. Note that we
> > already have "document property keywords" in org-mode. Less limited
> > since they're not positionally contained. And only for a limited set
> > of keywords; the "export keywords". (See [[info:org#Export Settings]])
> 
> "Document property keyword" has no syntactical meaning. It is used for
> fontification.

"Document property keywords" of today you mean? The export keywords?
It's a bit harsh to say it has no syntactical meaning. Ofc. it has -
its keywords that set properties on the document level! I agree that
it doesn't apply 100% correctly today for export keywords. But the
reason it doesn't seems to me to be an oversight, since we have the
export_{export-keyword} properties that do set properties. It's just a
bit convoluted. And /one of the reasons/ for proposing this change is
to try to clean things up, this included.

> I still don't get how this is an improvement. What would you be able to
> do with properties drawers that you cannot do currently with regular
> keywords? This is a genuine question: I don't want to turn down your
> suggestion, but I think it entails a lot of changes, and I want to be
> sure there is a real benefit to it.

My text above and the first mail do give arguments on why... But to
try to give some more:

- I think there is merit to the idea of a document being seen as a
  level-0 node. I think we'd benefit by adhering to the principles for
  outline nodes also for the document-node (level-0 node) as much as
  possible.

- I'd like the specification for org-mode to be clear and succinct and
  it's features to be as congruent as possible.

As a final note, I want to say that code already exist for
document-properties. It works and it's not terribly complicated,
although I'm sure you'll have comments on my code!

[fn:1] [[info:org#Export Settings]]

[fn:2] Unfortunately for export-keywords, the property-syntax differs
a bit from the keywords and they need the prefix =export_= to work.
That's surely something that can be fixed to align things though.


Kind regards, and respectfully
Gustav Wikström