[O] Asynchronous session evaluation

[Jack Kamm]

For some time I've been wishing for asynchronous Babel session
evaluation. So I've created an experimental branch implementing this. I
have an initial version working for R, so I thought it'd be a good time
to seek feedback and gauge interest.

To test the attached patch, add ":async yes" to an R session block
with a long computation (or "System.sleep") in it. Upon evaluation,
your Emacs won't freeze to wait for the result -- instead, a
placeholder will be inserted, and replaced with the true result when
it's ready.

I'll note how this is different from some related projects. ob-async
implements asynchronous evaluation for Babel, but it doesn't work with
sessions. emacs-jupyter, ein, and ob-ipython all implement asynchronous
session evaluation, but only for Jupyter kernels. Jupyter is great for
some cases, but sometimes I'd prefer not to use it. For example, the
native R console has great Emacs support via ESS, whereas the Jupyter R
console doesn't work with ESS and is not widely used in the R community.

Note that if you use ob-async, make sure to add "R" to
`ob-async-no-async-languages-alist' before testing this.

The new functionality is mainly implemented in
`org-babel-comint-async-filter', which I've defined in ob-comint.el,
and added as a hook to `comint-output-filter-functions'.  Whenever new
output is added to the comint buffer, the filter scans for an
indicator token (this is inspired by
`org-babel-comint-with-output'). Upon encountering the token, the
filter uses a regular expression to extract a UUID or temp-file
associated with the result, then searches for the appropriate location
to add the result to.

I've tried to make behavior as similar as possible to existing
ob-comint behavior, so that some of the existing code for interacting
with ob-comint can be refactored and reused. Still, it will be a large
task to add this feature for all languages. So far, I've only done R,
but my thought is to implement a few more languages before nailing
down the functionality. But, I hope something like this could be
merged in supporting just a subset of languages initially, then
gradually increasing the number of supported languages over time.

>From f1c198a85666507164e9a97a7e0758f1d5dcf126 Mon Sep 17 00:00:00 2001
From: Jack Kamm 
Date: Sat, 1 Jun 2019 12:26:13 -0700
Subject: [PATCH] Add asynchronous Babel comint & R eval

---
 lisp/ob-R.el  | 174 +-
 lisp/ob-comint.el | 152 +++--
 testing/lisp/test-ob-R.el |  24 ++
 3 files changed, 305 insertions(+), 45 deletions(-)

diff --git a/lisp/ob-R.el b/lisp/ob-R.el
index 9e738a8a5..74336d083 100644
--- a/lisp/ob-R.el
+++ b/lisp/ob-R.el
@@ -161,8 +161,8 @@ This function is called by `org-babel-execute-src-block'."
 		 (cdr (assq :session params)) params))
 	   (graphics-file (and (member "graphics" (assq :result-params params))
 			   (org-babel-graphical-output-file params)))
-	   (colnames-p (unless graphics-file (cdr (assq :colnames params
 	   (rownames-p (unless graphics-file (cdr (assq :rownames params
+	   (async (cdr (assq :async params)))
 	   (full-body
 	(let ((inside
 		   (list (org-babel-expand-body:R body params graphics-file
@@ -178,12 +178,11 @@ This function is called by `org-babel-execute-src-block'."
 	   (result
 	(org-babel-R-evaluate
 	 session full-body result-type result-params
-	 (or (equal "yes" colnames-p)
-		 (org-babel-pick-name
-		  (cdr (assq :colname-names params)) colnames-p))
+	 (org-babel-R-get-colnames-p params)
 	 (or (equal "yes" rownames-p)
 		 (org-babel-pick-name
-		  (cdr (assq :rowname-names params)) rownames-p)
+		  (cdr (assq :rowname-names params)) rownames-p))
+	 (equal "yes" async
   (if graphics-file nil result
 
 (defun org-babel-prep-session:R (session params)
@@ -369,11 +368,15 @@ Has four %s escapes to be filled in:
 4. The name of the file to write to")
 
 (defun org-babel-R-evaluate
-  (session body result-type result-params column-names-p row-names-p)
+(session body result-type result-params
+	 column-names-p row-names-p async-p)
   "Evaluate R code in BODY."
   (if session
-  (org-babel-R-evaluate-session
-   session body result-type result-params column-names-p row-names-p)
+  (if async-p
+	  (org-babel-R-evaluate-session-async
+	   session body result-type column-names-p row-names-p)
+	(org-babel-R-evaluate-session
+	 session body result-type result-params column-names-p row-names-p))
 (org-babel-R-evaluate-external-process
  body result-type result-params column-names-p row-names-p)))
 
@@ -395,11 +398,7 @@ last statement in BODY, as elisp."
 			   (format "{function ()\n{\n%s\n}}()" body)
 			   (org-babel-process-file-name tmp-file 'noquote)))
(org-babel-R-process-value-result
-	(org-babel-result-cond result-params
-	  (with-temp-buffer
-	(insert-file-contents tmp-file)
-	(org-babel-chomp 

[O] org-capture template to type in bills from shops in ledger format

[Stefan Huchler]

I wrote this template to capture my bills from mostly one shop, but it
has support for multiple shops and the important feature is that it
suggests previous item names and remembers last prices, that gives you
lot's of autocompletion if you repetetivly buy often the same stuff over
and over again.

#+begin_src emacs-lisp
%(let* ((default-directory (file-name-directory "%F"))
(map-file "shop-items.txt"))
   (load-file "helper.el")
   (require 'dash)
   (let* ((shops (if (file-exists-p map-file)
 (read-from-file map-file) '()))
  (names (mapcar 'car shops))
  (shop-name (ido-completing-read "Shop: " names nil nil nil))
  (new-prices) (new-names) (new-amounts)
  (products (assoc-default shop-name shops)))
 (while (let* ((names (mapcar 'car products))
   (name (ido-completing-read "Name: " names))
   (amount (read-number "Amount: " 1))
   (item (alist-get name products))
   (item (if (stringp item) (string-to-number item) item))
   (price (read-number "Price: " (or item 2.00
  (setq new-names (append new-names (list name)))
  (setq new-prices (append new-prices (list price)))   
  (setq new-amounts (append new-amounts (list amount)))
  (y-or-n-p "More items? ")))
 (let* ((-compare-fn (lambda (x y) (equal (car x) (car y
(new-products (mapcar* 'cons new-names new-prices))
(combined-products (-distinct (append new-products products)))
(combined-shops (-distinct (append `((,shop-name . 
,combined-products)) shops)))
(format-string "  expenses:food:%s \t\t%s St @ =€%s")
(format-function (lambda (name amount price)
   (format format-string name amount price)))
(product-lines (mapcar* format-function new-names
 new-amounts new-prices))
(shopping-items (s-join "\n" product-lines))
(total (reduce '+ (mapcar* '* new-amounts new-prices
   (print-to-file map-file combined-shops)
   (concat (format "  %(org-read-date nil nil) * %s\n%s"
   shop-name shopping-items)
   (format "\n  assets:bank:chequing\t\t€-%s"
   (read-string "Total: " (format "%.2f" total)))
#+end_src

Any thoughts? It's supposed to output into a org file with a embeded
ledger src block so you would have to check the alignment if you would
want to output to a normal ledger file.

here are the 2 functions from helper.el:

#+begin_src emacs-lisp
(defun print-to-file (filename data)
  (with-temp-file filename
(let* ((print-length 5000))
  (prin1 data (current-buffer)

(defun read-from-file (filename)
  (with-temp-buffer
(insert-file-contents filename)
(cl-assert (eq (point) (point-min)))
(read (current-buffer
#+end_src

Maybe that's useful for somebody else or somebody wants to suggest other
features or something. The only thing I would maybe consider to switch
is to use a json format for the shop-items.txt for the prices for easier
manual editing.

that's how I set it up:

#+begin_src emacs-lisp
("s" "(S)hopping" plain
 (file+function "path/finances.org"
(lambda () ""
  (progn (org-babel-goto-named-src-block "balance")   
 
(org-babel-goto-src-block-head)(forward-line
 "%[~/capture-templates/template-name]" 
 :jump-to-captured t
 :empty-lines-after 1
 :immediate-finish nil)
#+end_src 

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

[Gustav Wikström]

Hi Nicolas,

> -Original Message-
> From: Nicolas Goaziou 
> Sent: den 1 juni 2019 23:01
> To: Gustav Wikström 
> Cc: emacs-orgmode@gnu.org
> Subject: Re: Proposal for new document-level syntax
> 
> I only skimmed over your proposal, as I don't have much time. I'm sorry
> if you answered this already, but I don't understand how what you
> suggest would differ from regular keywords.

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}

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. 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]]) 

The proposal has a side-effect of reducing the complexity for
keywords.[fn:1] I did an evaluation of available keywords in org-mode
today by going through the documentation. And there are *lots* of uses
for keywords today. Making keywords easier to use, by removing the
need for them in many cases, hopefully will help future org-moders.

[fn:1] All keywords that have outline property equivalences can be
deprecated and later removed since we're introducing a property drawer
on the document level. All keywords that are meant for customizations
that don't have an outline property equivalent can be *moved* into the
setting drawer. That only leaves keywords that have real meaning in
the outline. =#+NAME=, =#+TOC=, =#+INCLUDE=, for example.

> 
> As a reminder:
> - you can create, and support, as many keywords as you want;
> - keywords all operate at the "document-level";
> - keywords can be located anywhere in the document.
> 
> I think Org keywords already provide everything you need. If they
> don't, I would suggest to improve them instead of creating something
> else.

In my opinion property drawers is the improvement which in time will 
make the existing property-keyword redundant.

With regards,
Gustav

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

[Nicolas Goaziou]

Hello,

Gustav Wikström  writes:

>   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: ...).

I only skimmed over your proposal, as I don't have much time. I'm sorry
if you answered this already, but I don't understand how what you
suggest would differ from regular keywords.

As a reminder:
- you can create, and support, as many keywords as you want;
- keywords all operate at the "document-level";
- keywords can be located anywhere in the document.

I think Org keywords already provide everything you need. If they don't,
I would suggest to improve them instead of creating something else.

WDYT?

Regards,

-- 
Nicolas Goaziou

[O] [SOLVED] (was: how to pass parameters to latex environment when exporting)

[Uwe Brauer]

>>> "UB" == Uwe Brauer  writes:

>>> "UB" == Uwe Brauer  writes:
> [Snip]...

>> But I would like to have 
>> \begin{solution}[5cm]

>> How can I pass that parameter when exporting? Thanks 

> According to 
> https://emacs.stackexchange.com/questions/34751/org-mode-latex-environment-in-drawer

> #+ATTR_LATEX: options: [Here]{There}{That}

> #+begin_fancyquote 
> Something witty!
> #+end_fancyquote

> Should work, it does not work for me

The following  works

#+ATTR_LATEX: :options [2in]

Re: [O] how to pass parameters to latex environment when exporting

[Uwe Brauer]

>>> "UB" == Uwe Brauer  writes:


[Snip]...

   > But I would like to have 
   > \begin{solution}[5cm]

   > How can I pass that parameter when exporting? Thanks 

According to 
https://emacs.stackexchange.com/questions/34751/org-mode-latex-environment-in-drawer

#+ATTR_LATEX: options: [Here]{There}{That}
#+begin_fancyquote 
Something witty!
#+end_fancyquote

Should work, it does not work for me


smime.p7s
Description: S/MIME cryptographic signature

[O] how to pass parameters to latex environment when exporting

[Uwe Brauer]

Hi 

I have the following example of a org file 

#+begin_solution
The result is as follows
#+begin_src matlab :results output raw :exports results  :eval never-export 
l=0.33;
mypois=poisspdf(0,l);
myres=1-poisspdf(0,l)-poisspdf(1,l);
disp('\begin{align*}')
fprintf('P(X\\geq 1)&=1-P(X=0)-P(X=1)=1- %g \n', mypois)
fprintf('P(X\\geq 1)&= %g \n', myres)
disp('\end{align*}')
l=1/3;
mypois=poisspdf(0,l);
myres=1-poisspdf(0,l)-poisspdf(1,l);
disp('\begin{align*}')
fprintf('P(X\\geq 2)&=1-P(X=0)=1- %g \n', mypois)
fprintf('P(X\\geq 2)&= %g \n', myres)
disp('\end{align*}')
#+end_src


#+RESULTS:
\begin{align*}
P(X\geq 1)&=1-P(X=0)-P(X=1)=1- 0.718924 \\
P(X\geq 1)&= 0.0438314 
\end{align*}
\begin{align*}
P(X\geq 2)&=1-P(X=0)=1- 0.716531 \\
P(X\geq 2)&= 0.0446249 
\end{align*}
\begin{align*}
P(X\geq 1)&=1-P(X=0)-P(X=1)=1- 0.718924 \\
P(X\geq 1)&= 0.0438314 
\end{align*}
\begin{align*}
P(X\geq 2)&=1-P(X=0)=1- 0.716531 \\
P(X\geq 2)&= 0.283469 
\end{align*}

#+end_solution


That is exported to 

\begin{solution}
The result is as follows
\begin{align*}
P(X\geq 1)&=1-P(X=0)-P(X=1)=1- 0.718924 \\
P(X\geq 1)&= 0.0438314 
\end{align*}
\begin{align*}
P(X\geq 2)&=1-P(X=0)=1- 0.716531 \\
P(X\geq 2)&= 0.0446249 
\end{align*}
\begin{align*}
P(X\geq 1)&=1-P(X=0)-P(X=1)=1- 0.718924 \\
P(X\geq 1)&= 0.0438314 
\end{align*}
\begin{align*}
P(X\geq 2)&=1-P(X=0)=1- 0.716531 \\
P(X\geq 2)&= 0.283469 
\end{align*}
\end{solution}
\end{document}

But I would like to have 
\begin{solution}[5cm]

How can I pass that parameter when exporting? Thanks 

Regards

Uwe Brauer 

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

[Gustav Wikström]

Hi Eric!

> -Original Message-
> From: Fraga, Eric 
> Sent: den 1 juni 2019 15:18
> To: Gustav Wikström 
> Cc: emacs-orgmode@gnu.org
> Subject: Re: [O] Proposal for new document-level syntax
> 
> For me, however, your proposed structure would clash strongly with my
> usual working practice.  Specifically, I put all customizations and
> settings at the end of my documents, along with, for instance, Emacs
> file local variables.  These are things I do not change often and
> usually don't care to see.  At the start of the document, however, is
> the real content.  So, I don't particularly like the idea of having
> settings etc. *before* the content in my files.

Point taken. File local variables potitions would not be affected of
course. And to be honest, I don't see any existing keyword going away
any time soon either. So your workflow probably won't be affected for
a long time. Unless you choose to!

With that said, I'd still like to argue a bit more for the structure
I've presented. The idea with having drawers is exactly the point
you're also making; that it makes configuration go out of the way for
real content. I question the disctraction 1-2 rows provide. Take for
example the way current property drawer and planning-properties work
on outline-nodes. They have fixed positions at the top of the node and
take up maximum two rows when declared. Not really an issue in my book
and the benefit of fixed positions is easy parsing for both humans and
the machine. The same would apply for document settings and
properties. Take the example below:

#+begin_example
  :SETTINGS:...
  :PROPERTIES:...
  ,* Heading 1
  DEADLINE: <2019-06-02 Sun> SCHEDULED: <2019-06-01 Sat>
  :PROPERTIES:...
  lorem

  ,* Heading 2
  Ipsum

  ,# -*- mode: org -*-
#+end_example

To me it makes perfect sense to have the drawers at the top at fixed
positions. It follows current convention for headlines. At most two
rows before the real content is hopefully a compromize that can be
made for syntactic clarity and simplicity. And personally it would be
a great improvement over the current way document-level keywords work.
> 
> Just by 2¢.

Thanks!

[O] bug#35419: [Proposal] Buffer Lenses and the Case of Org-Mode (also, Jupyter)

[Ihor Radchenko]

Dear Dmitrii,

Regarding the question about buffer-lens interaction. Let's take even
more complicated example:  To run the command, the user hits some key
combination, which happens to be bound to different commands in the main
buffer and in the lense buffer (i.e. the main buffer is in org-mode, the
lense is in mingus-mode, and the key is C-d). What should be the
behaviour in such a case? run the commands in both the buffers? decide
depending on the point position? It is easy to make up similar
complicated examples if you consider some exotic major modes in the
lense buffer.

I think that it would be more effective if someone decide on some basic
approach for the low-level implementation of the lense-mode (which
probably involves modifying emacs C-level source code) and continue the
discussion according to the benefits/limitations of that kind of
implementation.

Best,
Ihor

Dmitrii Korobeinikov  writes:

> Dear Ihor,
>
>> Note that indirect buffers always share *all* the contents with the master
>> buffer. As a result, it may not be easy to make things like flyspell
>> work on code blocks in org-mode, if these code blocks are treated as
>> lenses.
>
> I tried flyspell w/ different dictionaries on 2 buffers.
> The dictionary is switched every time I switch into one of the buffers.
> You are right, ispell and the like working w/ a file directly would have to
> learn to work w/ indirect buffers by managing multiple simultaneous
> processes.
> Fortunately, that doesn't seem like a big hurdle.
>
>>> (1) A question: when an indirect buffer is created and some region is
>>> narrowed to, is the rest of the buffer duplicated in memory somewhere? If
>>> this is so, there could be a useful efficiency-related modification to
>>> indirect buffers, which would allow "hard-narrowing": not duplicating the
>>> rest of the base buffer.
>>
>> There is no duplication of the buffer content in indirect buffers.
>> Internally, indirect buffer's content is a pointer to the main buffer
>> content. If you modify text in any of the indirect buffers or in the
>> main buffer, the text is modified in all of them and in the main buffer.
>> Only the buffer-local variables are duplicated.
>> You can refer to "27.11 Indirect Buffers" in the elisp manual for
>> details.
>
> Bad choice of wording on my side, I didn't mean duplication, but rather
> keeping unnecessary info, like text properties in the newly created
> indirect buffer, in the regions which were "permanently" chosen to be
> narrowed-out.
> Anyway, this is a premature optimization for now.
>
>> > The next immediately outstanding question is:
>> > (2) how can "embedding" (of a buffer as a part of another buffer as an
>> > area) be done efficiently? This could possibly be approached as two
>> > problems: (i) displaying the area and (ii) interacting with it.
>> > Any ideas?
>>
>> These issues have been discussed in
>> https://lists.gnu.org/archive/html/emacs-devel/2018-07/msg00863.html.
>> As I remember, the discussion stopped without a clear conclusion. It was
>> not clear how to separate the main buffer contents from the nested
>> buffer (I treat them as analogue of the buffer lenses). Another issue
>> was how the keymaps and buffer-local variables would interact when the
>> point is within a lense. It was not clear what should be the priority.
>
> The short answer is probably that lens-mode looks at the changes to the
> buffer and decides what's what.
> Here is my vision for this.
>
> Say, you have an indirect buffer, call it A, it's base has contents:
>
>> line 1
>> line 2
>> line 3
>
> Also, there is a buffer, call it B, where we want to embed A, with contents:
>
>> word 1
>> instruction: lens that displays A
>> word 2
>
> Lens-mode decides to identify the second line as a lens and constructs
> layout of the file.
>
>> [text]
>> [lens#A]
>> [text]
>
> Now, construct and display the final buffer as:
>
>> word 1
>> line 1
>> line 2
>> line 3
>> word 2
>
> The core question: how is this "displaying" done.
> In part, somewhat like how indirect buffers function.
> A displayed piece of text is a pointer/reference to the text in the
> indirect buffer.
> Of course, this should be done in a way so that the modes running in B
> don't change the properties of the text (following the layout constructed
> by lens-mode as in the example above). Though, this might better be
> done at the display unit level.
>
> What about interaction?
> Well, when the cursor is inside the lens, the controller decides what to do
> w/ each keybinding, whether to redirect it to the indirect buffer or not.
> And what about the case when borders are crossed?
> As I see it, any code that executes - does so as is.
> For instance, consider a buffer with a lens (contents: "lens"), which looks
> like this: "word1 lens word2".
> Place the cursor on the first word, run a command to remove 2 words.
> Now there are to possibilities here, depending on the implementation of the
> function which does the removal:
> 1. 

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

[Fraga, Eric]

On Saturday,  1 Jun 2019 at 15:45, Achim Gratz wrote:
> If the customization data isn't visible by default, does that address
> your concerns?

It might indeed.  Depends on how intrusive it is and how easy it is to
manage.

But having said this, and my previous email, don't take my views too
much into account in your development of this proposal.  My use cases
for org generally are not requiring the type of changes you are
suggesting.  I do understand your motivation but I tend to work with
small numbers of large files instead of the other way around.  A given
project will typically be contained in a single file that that file
will, for instance, have an "* [/] TODO Actions" headline etc.

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.2.3-379-gff2bf2

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

[Achim Gratz]

Fraga, Eric writes:
> For me, however, your proposed structure would clash strongly with my
> usual working practice.  Specifically, I put all customizations and
> settings at the end of my documents, along with, for instance, Emacs
> file local variables.  These are things I do not change often and
> usually don't care to see.  At the start of the document, however, is
> the real content.  So, I don't particularly like the idea of having
> settings etc. *before* the content in my files.

If the customization data isn't visible by default, does that address
your concerns?


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Wavetables for the Terratec KOMPLEXER:
http://Synth.Stromeko.net/Downloads.html#KomplexerWaves

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

[Fraga, Eric]

On Saturday,  1 Jun 2019 at 10:15, Gustav Wikström wrote:
>   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!

Dear Gustav,

thanks for this proposal.  I do understand your motivation for this and
can see a document level entity being useful.  

For me, however, your proposed structure would clash strongly with my
usual working practice.  Specifically, I put all customizations and
settings at the end of my documents, along with, for instance, Emacs
file local variables.  These are things I do not change often and
usually don't care to see.  At the start of the document, however, is
the real content.  So, I don't particularly like the idea of having
settings etc. *before* the content in my files.

Just by 2¢.

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.2.3-379-gff2bf2

[O] [PATCH] * doc/org-manual.org (External Links): Fix URL

[Gregor Zattler]

---
 doc/org-manual.org | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 469e16402..583840a74 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3081,7 +3081,7 @@ External links are URL-like locators.  They start with a 
short
 identifying string followed by a colon.  There can be no space after
 the colon.  The following list shows examples for each link type.

-| =http://www.astro.uva.nl/=dominik=| on the web |
+| =https://staff.science.uva.nl/c.dominik/= | on the web |
 | =doi:10.1000/182= | DOI for an electronic resource |
 | =file:/home/dominik/images/jupiter.jpg=   | file, absolute path|
 | =/home/dominik/images/jupiter.jpg=| same as above  |
--
2.11.0

[O] Proposal for new document-level syntax

[Gustav Wikström]

 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]


[#118] 

[#91] 

[#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