Re: Inserting a comma as prefix of headlines (in Org code blocks)

[Nicolas Goaziou <n.goaziou@gmail.com>]

Bastien <bzg@altern.org> writes:

> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>
>> Ok then another binding. I still think freeing "," key is the best thing
>> to do. More on this below.
>
> Users will still be able to use the "," so this will not really fix
> the issue.

That's the whole point: leave the ability to escape the headline
manually (without using "C-q ,"), as Org should be unable to do so.

> The fact that (org-in-block-p '("src")) returns a non-nil value in
>
> #+begin_src org
> ** H12
> #+end_src
>
> is not wrong in the context of checking whether a speed command should
> be prevented or not.  It might be wrong in other contexts, but for
> this purpose it is not.

It is wrong because there's no block here, although it finds one.
Functions should not be built on erroneous assumptions like this.

> That's similar to TAB, which comma-escapes the content of the block
> instead of cycling through the folding states, because it knows it is
> in a src block.

It cannot know. If there's a headline amidst a "block", that "block"
dissolves because its opening line is separated from the closing one.

Again, headlines are first-class objects in Org. A command shouldn't
pretend there is no headline when point is on one. TAB has to cycle in
this case (like it does in an example block, for example), even if it
looks strange on trivial examples.

>>   1. "stars + space" at column 0 define a headline. No exception. Most
>>      of Org code (reasonably) assumes this, so we should not let users
>>      think otherwise.
>
> Yes.  But it is not because the cursor is at the beginning of a
> headline that every function should behave the same.  TAB does not,
> speed commands do not either.

Since headlines are the base of Org syntax, I think it should be
expected that commands always behave consistently on them.

There is no more important context than a headline. Ignoring it may look
useful on a couple of examples, but we're shooting ourselves in the
foot. Think about it, for example:

  #+begin_src something
  ...
  more than one screenful of lines
  ...
  * Headline
  ...
  more than one screenful of lines
  #+end_src

Appending a comma to "* Headline" after pressing TAB may be surprising
if the user has forgotten about the context.

Another example:

  #+BEGIN_src emacs-lisp
  * H1
  ** H11
  #+END_src

Press TAB on any of the headlines. It will neither cycle them nor add
a comma in front of them.

This hack is not worth it. It's far better to have a simple rule to
handle them: "If you need to have a star at column 0 in a block, put
a comma before it.". One line in the manual is better than scores of
loc, which can always be fooled under certain circumstances.

>>   2. Do not rely on `org-in-block-p'. Please use `org-element-at-point'
>>      or `org-element-context' instead. These are not broken, and they
>>      are fast enough for any interactive use (but let's not use them for
>>      fontification yet).
>
> Btw, can you think of cases where it would be nice to have
> `org-element-context' check against a wider context than the closest
> one?

`org-element-context' already provides access to wider context
through :parent property. In the following example:

  *bold _and_ underlined text*

with, point on "and",

  (org-element-type (org-element-property :parent (org-element-context)))

will return `bold' and

  (org-element-type
    (org-element-property :parent
      (org-element-property :parent (org-element-context))))

will return `paragraph'.


Regards,

-- 
Nicolas Goaziou