emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[O] Proposal for new document-level syntax


From: Gustav Wikström
Subject: [O] Proposal for new document-level syntax
Date: Sat, 1 Jun 2019 10:15:32 +0000

                ________________________________________

                 PROPOSAL FOR NEW DOCUMENT-LEVEL SYNTAX

                            Gustav Wikström
                ________________________________________


Table of Contents
_________________

1. Summary
2. Background, details etc.
3. Proposal details
4. Code?


1 Summary
=========

  I propose a "document" element in org-element, a property-drawer on
  document-level, a setting-drawer on document-level and
  property-keywords (slightly different than what already exist). And
  would like your comments regarding that!

  More details below.


2 Background, details etc.
==========================

  I'm amazed by how well org-mode fullfills my needs for writing,
  thinking, organizing and structuring information. Having a text-based
  outliner with rich formatting, searching and inter-linking options is
  amazing! There are a few things that's bugged me for a while though.
  One of those things is the fact that org-mode is lacking when you're
  outside of a headline. Basically, org-mode lacks the proper notion of
  a document. One use case for a more clear notion of a document is for
  large libraries of short notes separated by files instead of separated
  by headlines. Separating notes by files has drawbacks today. You can't
  easily define todo's, tags, ID's, attachments etc. when your not
  within a headline!

  You might think: "But just create a headline if you want those
  things..!"

  To which I'd answer: "Yes, that works. As a workaround. But it's not
  good enough! What do I name my headline? I already have a name for the
  file, having to define a name again for a headline inside that file is
  redundant for short notes."

  Look for example at org-brain which had to introduce separate concepts
  to be able to deal with files and subtrees ([headlines and files]).
  Some org-brain issues that relates to this lack of a document-concept:
  ([#118], [#91], [#48]). This suggestion is not about org-brain. But I
  just wanted to give an example of how this is something that /can/ be
  improved.

  To get started on this road towards a clearer definition and syntax
  for things above the headline-concept, I have a couple of suggestions
  I hope the community will support!


[headlines and files]
<https://github.com/Kungsgeten/org-brain#headline-and-file-entries>

[#118] <https://github.com/Kungsgeten/org-brain/issues/118>

[#91] <https://github.com/Kungsgeten/org-brain/issues/91>

[#48] <https://github.com/Kungsgeten/org-brain/issues/48>


3 Proposal details
==================

  I propose to introduce two org-mode drawers to be used in the top of
  org-mode documents:
  1) A setting drawer. Applicable only if positioned at the top of a
     buffer, below any potential comment-line or document-level keywords
     (more on those later).
  2) A property drawer. Applicable with the same positional condition as
     the settings-block, and positioned after the settings-block if both
     blocks are available.

  I also propose to allow for whatever property to be defined as a
  keyword if also defined at the top of the document.

  Details for these proposals follows:

  The setting drawer makes the following keywords redundant:
  - #+STARTUP
  - #+TODO
  - #+SEQ_TODO
  - #+TYP_TODO
  - #+PRIORITIES
  - #+TAGS
  - #+LINK
  - #+CONSTANTS
  - #+SETUPFILE
  - #+MACRO

  Initially I propose to just use the setting drawer as an additional
  syntax allowed for the above keywords, preferably with a new
  helper-method for setting them. Settings defined in this drawer should
  have precedence over settings defined by the keywords above. Long term
  I'd like to depricate the above keywords in favour of the setting
  drawer.

  The property drawer is used for properties defined at node-level 0.
  Properties defined inside this drawer are applied in exactly the same
  way as properties on headline-entries are applied for it's subtree.
  I.e. the same inheritance-rules apply.

  The property drawer makes the following keywords redundant: (since all
  of them have property drawer equivalences)
  - #+PROPERTY
  - #+OPTIONS
  - #+CATEGORY
  - #+FILETAGS
  - #+COLUMNS
  - #+ARCHIVE

  Defining properties on the document-level should work using the same
  commands as today when the point is before the first headline.
  Properties defined in the document property drawer should have
  precedence over properties defined by the (then redundant) keywords
  above.

  I propose to allow properties to be defined also as document property
  keywords. All keywords in the top of a buffer, before any non-comment
  line, are document-level keywords. In effect, they are properties that
  apply in exactly the same way as properties defined in the property
  drawer. The only reason for using a document keyword instead of
  defining it inside the property drawer is to make it more visible. One
  example would be the title-keword (#+TITLE: ...).


4 Code?
=======

  Work in progress can be found here:
  <https://github.com/Whil-/org-mode>

  With separate branches in an attempt to isolate things from each
  other:
  New document element
        
<https://github.com/Whil-/org-mode/tree/feature/org-document-formalization>
  Document property drawer
        
<https://github.com/Whil-/org-mode/tree/feature/org-document-property-drawer>
  Document property keywords
        
<https://github.com/Whil-/org-mode/tree/feature/org-document-property-keywords>
  Document setting drawer
        
<https://github.com/Whil-/org-mode/tree/feature/org-document-setting-drawer>

  The first two branches are working already (though lacking
  documentation) while the two last ones mostly exist as ideas. Note
  that of these branches most likely will get their history rewritten
  from time to time. I.e they're public... but dangerous!

reply via email to

[Prev in Thread] Current Thread [Next in Thread]