seeking advice on use of drawers vs blocks

seeking advice on use of drawers vs blocks

[Christian Wittern]

Dear Orgmoders,

Today I would like to poll the collective wisdom of the Orgmode user
community about a design question I have.

Since discovering org-mode more than 9.5 years ago (yeah! ), it has
transformed my life almost as much, maybe even more than Emacs itself.
Among other things, for work I have developed a package called Mandoku,
which uses the org-mode format to deal with (classical) Chinese text.  For
those interested, a description of this format, which is 99% org-mode is
here[1].

Now, as described at the very end of that page, I allow users to maintain
annotations to things on the previous line of text in drawers. I then have
scripts to collect these annotations and do various interesting things with
them.  Now, since I started doing this some 6+ years ago, the org-mode
syntax has seen some changes and especially blocks seem much more advanced
now. I would like to have more expressive power concerning the content of
the annotations, so I am considering switching to a block format for these
annotations (or more likely for the time being, supporting both). This would
give me more metadata and control over the content, because I can have
header lines etc. However, my audience is somewhat non-technical and they
concentrate on reading the texts, so the intrusion has to be minimal.
Currently I handle that with the drawers being mostly folded and only
expanded on demand with a <tab> key on the line as usual, that is also the
reason to use a short word for the drawer, which is the only thing seen in
the folded state.

So this does not work so nicely with blocks, especially if the header line
expands.  Ideally I would even like to avoid seeing the header line in
folded state and just have an icon in the margin to indicate that there is
an annotation.  Does anybody know how this can be done? Has anybody done
something similar?

Apart from that, I wonder if there are other things to consider in the
question: Should I move to block syntax rather than staying with drawers?

Any and all comments appreciated,

Christian Wittern



[1] http://www.mandoku.org/mandoku-format-en.html

-- 
Christian Wittern, Kyoto

Re: seeking advice on use of drawers vs blocks

[Christian Moe]

Hi,

Mandoku looks very nice -- an inspiration.

I don't really know enough about what your users do or how you want to
process the blocks to venture an opinion. On the one hand, for the sake
of simplicity and continuity for your users (to say nothing of
aesthetics), I'd say keep the drawer format, and add what functionality
you need to add by defining further conventions and writing code to
process drawer contents. Org blocks are many wonderful things, but
unobtrusive they're not, and they look quite intimidating when you start
adding header lines and parameters. On the other hand, when Org already
has these powerful blocks, it does seem a bit wasteful to reinvent the
wheel, as well as less portable.

On the third hand, have you considered wrapping a block in a drawer? It
would only look worse after you've opened it, and you could provide a
template for insertion so users don't have to remember where all the
colons and pluses go. If you only need the added metadata/functionality
for some annotations, and not always, that might be a solution.

Yours,
Christian Moe

Christian Wittern writes:

> Dear Orgmoders,
>
> Today I would like to poll the collective wisdom of the Orgmode user
> community about a design question I have.
>
> Since discovering org-mode more than 9.5 years ago (yeah! ), it has
> transformed my life almost as much, maybe even more than Emacs itself.
> Among other things, for work I have developed a package called Mandoku,
> which uses the org-mode format to deal with (classical) Chinese text.  For
> those interested, a description of this format, which is 99% org-mode is
> here[1].
>
> Now, as described at the very end of that page, I allow users to maintain
> annotations to things on the previous line of text in drawers. I then have
> scripts to collect these annotations and do various interesting things with
> them.  Now, since I started doing this some 6+ years ago, the org-mode
> syntax has seen some changes and especially blocks seem much more advanced
> now. I would like to have more expressive power concerning the content of
> the annotations, so I am considering switching to a block format for these
> annotations (or more likely for the time being, supporting both). This would
> give me more metadata and control over the content, because I can have
> header lines etc. However, my audience is somewhat non-technical and they
> concentrate on reading the texts, so the intrusion has to be minimal.
> Currently I handle that with the drawers being mostly folded and only
> expanded on demand with a <tab> key on the line as usual, that is also the
> reason to use a short word for the drawer, which is the only thing seen in
> the folded state.
>
> So this does not work so nicely with blocks, especially if the header line
> expands.  Ideally I would even like to avoid seeing the header line in
> folded state and just have an icon in the margin to indicate that there is
> an annotation.  Does anybody know how this can be done? Has anybody done
> something similar?
>
> Apart from that, I wonder if there are other things to consider in the
> question: Should I move to block syntax rather than staying with drawers?
>
> Any and all comments appreciated,
>
> Christian Wittern
>
>
>
> [1] http://www.mandoku.org/mandoku-format-en.html

Re: seeking advice on use of drawers vs blocks

[Christian Wittern]

Dear Christian,
Thank you for your feedback.
On 2016-04-05 16:54, Christian Moe wrote:
> On the third hand, have you considered wrapping a block in a drawer?
No, I had not considered this.  Let me play around with that idea for a
while. Is this syntactically allowed? I remember there was a document
discussed a while ago that would define org syntax, but I can't remember now
where this document is.  Does anybody remember?

All the best,

Christian


-- 
Christian Wittern, Kyoto

Re: seeking advice on use of drawers vs blocks

[Christian Moe]

Hi,

The syntax document is at http://orgmode.org/worg/dev/org-syntax.html.
It defines drawers as a "greater element", and says that greater
elements may contain other greater elements. Exporting a sample block
wrapped in a drawer works fine with the d:t option. Other complications
may arise, though...

Yours,
Christian

Christian Wittern writes:

> Dear Christian,
> Thank you for your feedback.
> On 2016-04-05 16:54, Christian Moe wrote:
>> On the third hand, have you considered wrapping a block in a drawer?
> No, I had not considered this.  Let me play around with that idea for a
> while. Is this syntactically allowed? I remember there was a document
> discussed a while ago that would define org syntax, but I can't remember now
> where this document is.  Does anybody remember?
>
> All the best,
>
> Christian

Re: seeking advice on use of drawers vs blocks

[Christian Wittern]

Hi,

On 2016-04-07 18:05, Christian Moe wrote:
> The syntax document is at http://orgmode.org/worg/dev/org-syntax.html.
> It defines drawers as a "greater element", and says that greater
> elements may contain other greater elements. Exporting a sample block
> wrapped in a drawer works fine with the d:t option. Other complications
> may arise, though...

Great, thanks.  Yes, this answers a few other questions as well.  For
example, it seems that a drawer always has to end with :END: in capital
letters, using :end: is not possible (I usually prefer the non-shouting
variant if possible).

Christian

-- 
Christian Wittern, Kyoto

Re: seeking advice on use of drawers vs blocks

[Nicolas Goaziou]

Hello,

Christian Wittern <cwittern@gmail.com> writes:

> Great, thanks.  Yes, this answers a few other questions as well.  For
> example, it seems that a drawer always has to end with :END: in capital
> letters, using :end: is not possible (I usually prefer the non-shouting
> variant if possible).

":end:" is also valid. Syntax is case-insensitive, unless specified in
the document.

Regards,

-- 
Nicolas Goaziou

Re: seeking advice on use of drawers vs blocks

[Christian Wittern]

Dear Nicolas,
On 2016-04-07 20:57, Nicolas Goaziou wrote:
> ":end:" is also valid. Syntax is case-insensitive, unless specified in
> the document.
Thank you for this clarification.
All the best, Christian

-- 
Christian Wittern, Kyoto

Re: seeking advice on use of drawers vs blocks

[Marco Wahl]

Christian Wittern <cwittern@gmail.com> writes:

>> On the third hand, have you considered wrapping a block in a drawer?

> No, I had not considered this.  Let me play around with that idea for a
> while. Is this syntactically allowed? I remember there was a document
> discussed a while ago that would define org syntax, but I can't remember now
> where this document is.  Does anybody remember?

http://orgmode.org/worg/dev/org-syntax.html See "Drawers and Property
Drawers".


HTH,
-- 
Marco Wahl
GPG: 0x49010A040A3AE6F2