emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Proposal for new document-level syntax
@ 2019-06-01 10:15 Gustav Wikström
  2019-06-01 13:17 ` Fraga, Eric
                   ` (2 more replies)
  0 siblings, 3 replies; 12+ messages in thread
From: Gustav Wikström @ 2019-06-01 10:15 UTC (permalink / raw)
  To: emacs-orgmode@gnu.org

                ________________________________________

                 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!

^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2019-06-06  9:29 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-06-01 10:15 Proposal for new document-level syntax Gustav Wikström
2019-06-01 13:17 ` Fraga, Eric
2019-06-01 13:45   ` Achim Gratz
2019-06-01 14:01     ` Fraga, Eric
2019-06-01 15:53   ` Gustav Wikström
2019-06-01 21:00 ` Nicolas Goaziou
2019-06-01 23:08   ` Gustav Wikström
2019-06-03 20:39     ` Nicolas Goaziou
2019-06-06  7:50       ` Gustav Wikström
2019-06-02  7:35 ` Norman Walsh
2019-06-02 22:49   ` Samuel Wales
2019-06-06  9:29   ` Marco Wahl

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).