Re: [RFC] Document level property drawer

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

[-- Attachment #1: Type: text/plain, Size: 3402 bytes --]

Hi!

I'll start with the most important info at the top. I've applied the
patch! But before anyone comes screaming I'll just say it's applied on
a separate branch. After consultation with Nicolas Goaziou that was
seen as the most reasonable thing to do. The idea is that it's high
time to start wrapping up 9.3 for a release and (even though I
personally would like to have this in there) since this patch might
continue to generate discussion and possibly bugs and fixes it's more
safe to let this come after the 9.3 release.

Sooo, a separate branch is created in the Org mode repository named
"next". I'm not entirely sure how we're supposed to work with it. But
I've anyways pushed my (non-breaking) patch there.

Comments on what you've written below!

Marco Wahl writes:

> > @Marco Wahl; As I understand you've applied the patch and tried it
> > out. Have you found any issues yet? What do you think of the patch
> > after having used it for a while?
> 
> Indeed I applied your patch and have it applied still.  Please note that
> I did nothing fancy and in particular I did not try to break the patch.

Got it.

> The patch works good for me.

Nice to hear!

> Noteworthy observations AFAICT:
> 
> 1. I could not translate my personal "#+TODO: . N ~ | x c g >" into a
> respective :TODO: property.

Yes, that's true. The reason is that there is no TODO-property that
fits in property drawers right now. I.e. special properties such as
TODO, TAGS, priority, scheduling and deadlines that have special
syntax for the outline still have no defined meaning for outline level
0. I ofc. think that's an oversight ;) But I may also be a bit crazy. 

A conclusion to draw from that, that may be worth writing more about,
is that the property drawer for node level 0 will not be able to
replace all file-level keywords that exist today.  Only properties that
currently can also be defined in property drawers in the outline will
work in the property drawer on level 0.  Makes sense?

The idea I had for all the other keywords that apply for the whole
file was to create another drawer, what I called a settings drawer.
Because the TODO-keyword you refer to above really is a setting that
you're making for the current file, much the same as when you make
changes in global, folder local or file local variables using the
standard emacs framework.

I've attached an investigation I did of the world of Org mode
keywords. It was done quite a while back and some things in there are
subjective and may not represent my current picture of the "ideal".
Nonetheless, maybe an interesting read for the ... other crazy people
out there?

> 2. With org-ids turned on and point before the first heading, function
> org-store-link creates an org-id property at the document level.
> 
> Regarding number 1. I think a list of document-level properties which
> don't behave the same when used in the document property drawer would be
> nice.  Ideally this list is empty AFAICT.  Maybe I overlook something.
> Is this an issue?

Ahh, see the attachment ;) Maybe can give answers to some of your
thoughts.

> I think observation 2. is just a little surprise but turns out to be
> natural when the document level property drawer is enabled.

Glad to hear!

> 
> 
> Still +1 for the inclusion of the patch and HTH,
> -- 

Thanks
Gustav

[-- Attachment #2: Investigation.org --]
[-- Type: application/octet-stream, Size: 12130 bytes --]

:PROPERTIES:
:ID:       ccbcc594-6ea0-42d4-af6d-62b93bb951d1
:COLUMNS:  %item %has-entry-syntax
:END:
#+TITLE: Investigation of keywords in org-mode

There are LOADS of them. They are used for configurations of various
kind. Many have ambigous names and it's not always clear what they're
for or in what context they're used. Some are document-level content.
Some change the emacs org-mode state for the buffer. This node sums up
my investigation of them.

* Startup
:PROPERTIES:
:has-entry-syntax: nil
:END:
Used to customize the org-mode configuration for the current buffer.

- Visibility :: [[info:org#Initial visibility][info:org#Initial visibility]]
- Blocks :: [[info:org#Blocks][info:org#Blocks]]
- Column Width and Alignment :: [[info:org#Column Width and Alignment][info:org#Column Width and Alignment]]
- Setting constants-unit-system :: [[info:org#References][info:org#References]]
- Closing items :: [[info:org#Closing items][info:org#Closing items]]
- Setting org-tag-persistent-alist :: [[info:org#Setting Tags][info:org#Setting Tags]]
- Setting logging when scheduling stuff :: [[info:org#Inserting deadline/schedule][info:org#Inserting deadline/schedule]]
- Setting logging for repeated tasks :: [[info:org#Repeated tasks][info:org#Repeated tasks]]
- Logging Clocking in/out :: [[info:org#Clocking commands][info:org#Clocking commands]]
- Logging refiling :: [[info:org#Refile and Copy][info:org#Refile and Copy]]
- Setting org-Pretty-entities :: [[info:org#Special Symbols][info:org#Special Symbols]]
- Previewing Latex :: [[info:org#Previewing LaTeX fragments][info:org#Previewing LaTeX fragments]]
- Inline images customization :: [[info:org#Images][info:org#Images]]
- Footnotes customization :: [[info:org#Creating Footnotes][info:org#Creating Footnotes]]
- Setting beamer minor mode :: [[info:org#Editing support][info:org#Editing support]]
- Displaying headline-stars :: [[info:org#Clean View][info:org#Clean View]]
- Various other customization :: [[info:org#In-buffer Settings][info:org#In-buffer Settings]]

To see all options, =M-C-i= (pcomplete) on the following row:
#+STARTUP:

or look at the constant =org-startup-options= defined in org.el.

Common for all startup-keywords is that they take no parameters. Each
value has a predefined configuration. For example hideblocks &
nohideblocks are two startup-options that both set
org-hide-block-startup. But to different values.

Startup modifies the state of the run-time.

One benefit of having them is for easy and concise user-configuration
inside each buffer. But it basically is the same as setting file local
variables for safe Org mode defcustoms. Why not just promote that
instead? Or provide syntactic sugar for it inside a "settings
drawer"?!... That would both reduce complexity and increase
configurability.

Making the setting-drawer work similar to property-drawers might allow
for a "Set Startup" interactive function that can take the same
arguments as are available for the Startup-keyword today. I'm sure
using startup has it's merits for those who are used to it, so
depricating it in favour of another more general solution is not an
option.

* Property
:PROPERTIES:
:has-entry-syntax: t
:END:
The property keyword is used to set properties for the whole document.
Main intention seems to be for inheritance-purposes. When working in a
multi-file project (not yet supported that well...) having
document-properties are meaningful also without inheritance. One can
imagine a set of org-mode files without headlines in a folder where
one would want to set ID's for example, and link between the files
using these ID's.

Property-keywords can be defined anywhere inside the file, even inside
headlines. The property that is set using the keyword-syntax always
applies to the whole document (unless overridden in headlines). If one
property is defined multiple times the last definition is used.

*I propose to depricate property-keywords* in its current form, and
introduce (1) a property-drawer for the document node and (2) a new
kind of property-keyword that is only valid at a certain point in the
buffer. Properties in property-drawers should override the existing
properties set by (the existing) property-keyword, as long as both
ways to define document-level properties are supported.

** New kind of property-keyword
The new kind of property-keyword would be on the form
=#+{propertyname}: {propertyvalue}= and would only be applicable if
entered directly at the top of the buffer, below potential
comment-lines but before any blank line and before the setting drawer
and the property drawer. Ideally a property-keyword shall override a
property set in the document property drawer, if the keyword is
defined in both places.

* Options
:PROPERTIES:
:HAS-ENTRY-SYNTAX: t
:END:
The options-keyword is used solemly when exporting. This is
unfortunately not obvious by the naming of the keyword.

The same functionality exist also for subtrees. Then the
export-options are specified as properties with the key
'EXPORT_OPTIONS'.

*I propose to depricate the Options-keyword* and start using the
already existing property-syntax instead inside the proposed
document-level property-drawer.

* Various Export-keywords
:PROPERTIES:
:HAS-ENTRY-SYNTAX: t
:END:
Keywords such as Title, Subtitle, Author, Date, Email are documented
as "export-keywords". Ref: [[info:org#Export Settings][info:org#Export Settings]]

*I propose to relabel these keywords as document keywords*. That label
is more fitting and does not provide any negative side-effects since
an export anyways is supposed to export org-mode information. If
anything, the relabeling promotes the keywords to first-class citizens
within org-mode.

I also propose to specify a fixed set of document-keywords that
org-mode support (i.e. document them) and provide a command to easily
insert them into the buffer. The location of these keywords should be
at the top of the buffer, after potential comment-lines but before the
document-level settings-drawer and properties-drawer.

Unsupported document-keywords can also be included but might not be
guaranteed to be exported, or function correctly from other
perspectives. But by their location in the top of the buffer, they
should be recognized as document-keywords non the less.

The reason for not wanting to depricate the keywords for these
properties and delegate them to the properties-drawer is that these
are keywords that makes sense to visually promote inside a buffer. I'm
for example quite often using a =#+TITLE:= line to declare the title
of the document. Hiding that line inside the properties-drawer is
counter-intuitive. I might however want to "demote" some of the
document-level keywords into a drawer for various reasons. So allowing
document-keywords to also be specified as keywords makes sense.

* Category
:PROPERTIES:
:HAS-ENTRY-SYNTAX: t
:END:

Can either be defined at document-level with =#+CATEGORY= or at
entry-level with a property named the same.

*I propose to depricate the #+CATEGORY syntax* in favour of a category
property inside the proposed document-level property-drawer.

* Filetags
:PROPERTIES:
:HAS-ENTRY-SYNTAX: normal tag inheritance
:END:

Filetags are tags set on document-level.

*I propose to depricate the #+FILETAGS syntax* in favour of a tags
property inside the proposed document-level property-drawer.

Now this might be a bit confusing since the Tags-keyword also exist on
document-level. More on that in it's own entry: [[id:ba02b48b-261a-4e65-b9a2-dfc57391ae41][Tags]].

* Columns
:PROPERTIES:
:has-entry-syntax: t
:END:

Can either be defined at document-level with =#+COLUMNS= or at
entry-level with a property named the same.

*I propose to depricate the #+COLUMNS syntax* in favour of a columns
property inside the proposed document-level property-drawer.

* Archive
:PROPERTIES:
:HAS-ENTRY-SYNTAX: t
:END:

Can either be defined at document-level with =#+ARCHIVE= or at
entry-level with a property named the same.

*I propose to depricate the #+ARCHIVE syntax* in favour of an archive
property inside the proposed document-level property-drawer.

* TODO, SEQ_TODO, TYP_TODO
:PROPERTIES:
:HAS-ENTRY-SYNTAX: nil
:END:
Setting the default allowed todo-values for a buffer (using the local
variable =org-todo-keywords-1=.

*I propose to depricate the TODO-keywords* and instead add
them as available keys in the proposed settings-drawer.

* Priorities
:PROPERTIES:
:HAS-ENTRY-SYNTAX: nil
:END:
Setting default priority-values for a buffer.

*I propose to depricate the priorities-keyword* and instead add
priorities as an available key in the proposed settings-drawer.

* Tags
:PROPERTIES:
:HAS-ENTRY-SYNTAX: nil
:ID:       ba02b48b-261a-4e65-b9a2-dfc57391ae41
:END:

Tags-keyword is used when setting the buffer-local variable
org-current-tag-alist. This defines the default tags available for
autocompletion within the buffer.

There can be more than one Tags-keyword per file and all rows
accumulate together into the final list of tags available.

*I propose to depricate the tags-keyword* and instead add tags as a
keyword available in the proposed settings-drawer.

* Link
:PROPERTIES:
:HAS-ENTRY-SYNTAX: nil
:END:
Link-abbreviations that can be used throughout the document.

*I propose to depricate the link-keyword* and instead add link as a
keyword available in the proposed settings-drawer.

* Constants
:PROPERTIES:
:HAS-ENTRY-SYNTAX: nil
:END:
buffer-global constans that can be used by tables and nothing else.

Set by =org-set-regexps-and-options=, using
=org--setup-collect-keywords=, into
=org-table-formula-constants-local=. As I understand it.

They fit closely together with link-abbreviations in how the keywords
are used to populate buffer-wide special key-value pairs. They differ
from properties since they are special-purpose.

*I propose to depricate the constants-keyword* and instead add
constants as a key available in the proposed settings-drawer.

* Setupfile
:PROPERTIES:
:HAS-ENTRY-SYNTAX: nil
:END:
Outsourcing of settings to another file (or url).

*I propose to depricate the setupfile-keyword* and instead add
setupfile as a key available in the proposed settings-drawer.

* Macro
:PROPERTIES:
:HAS-ENTRY-SYNTAX: nil
:END:
Text snippets.

*I propose to depricate the Macro-keyword* and instead add
macro as a key available in the proposed settings-drawer.

* Inline-keywords
:PROPERTIES:
:HAS-ENTRY-SYNTAX: n/a
:END:
Keywords which are used to provide content at a certain location in the
file.

Keywords: =INCLUDE=, =TOC=, =ASCII=, =HTML=, =LATEX=, =ODT=,
=TEXINFO=, =BEAMER=, =INDEX=

I have no issue with these keywords.

* Affiliated keywords
:PROPERTIES:
:HAS-ENTRY-SYNTAX: n/a
:END:
Keywords that relates to or adds information to objects within the
buffer. List of keywords is found in
=org-element-affiliated-keywords=. (Ex. NAME, CAPTION, RESULT, etc.)

These are not of my concern here, I haven't used them much but when I
have I haven't had any problems with them. The functionality is clear.

* Misc
:PROPERTIES:
:HAS-ENTRY-SYNTAX: nil
:END:
There are more keywords... But with my current understanding there
were no keywords that would make my suggestions invalid. I just
didn't work my way through them all since I thought of them as very
specific and of minor importance.

** Bind
Used for very advanced exporting. They seem to apply to the whole
document but only when the document is being exported. I'll call it a
special kind of export keyword for now...

** Specific export-backend keywords
I didn't work my way though all export-backend keywords. My guess is
that most of them could fit into either of the proposed drawer, the
document-keywords section (for example the Description-keyword that
can be used in HTML-export) or that they are inline or affiliate
keywords, which I'm not addressing here.