bugs in commenting and filling

bugs in commenting and filling

[Samuel Wales]

Here are 6 bugs (or at least changes that might need to be
documented) in Org commenting and filling.

Context: commenting and filling used to use generic Emacs
facilities, but now use Org-specific ones.

original:

===
x

bug 1: the line above now does not get commented even if
comment-empty-lines is t.

  bug 2: this line now does not indent consistently with the
rest of emacs.
===

comment-dwim:

===
# x

# bug 1: the line above now does not get commented even if
# comment-empty-lines is t.

  # bug 2: this line now does not indent consistently with the
# rest of emacs.
===

  bug 3: outside of org with filladapt turned OFF, filling this
paragraph does not
indent it.  also auto-fill
indents unlike the rest of emacs.  ret tab is ok.

#bug 4: this paragraph now gets exported in HTML subtree
#export, which will likely surprise many people who formerly
#used "#" comments instead of "# " comments and don't
#carefully check all output.  they might
#even publish private information automatically without
#realizing it using old files that they forgot or did not
#know to convert.

#bug 5: filling this paragraph with "===" on the following
#line will fill the ===, unlike the rest of emacs with
#filladapt turned ON.  we are supposed to not use filladapt
#with org.  therefore, how do you emulate the filladapt
#behavior so that there is consistency between emacs and
#org?

Bug 6: what does the Org-specific commenting do?  i was not
able to determine that from the docstring to
org-comment-or-uncomment-region.  maybe update docstring
would help others trying to find out why commenting works
differently in org from the rest of emacs?

Hope it helps.

Thanks.

Samuel

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

Re: bugs in commenting and filling

[Nicolas Goaziou]

Hello,

Samuel Wales <samologist@gmail.com> writes:

> Here are 6 bugs (or at least changes that might need to be
> documented) in Org commenting and filling.
>
> Context: commenting and filling used to use generic Emacs
> facilities, but now use Org-specific ones.
>
> original:
>
> ===
> x
>
> bug 1: the line above now does not get commented even if
> comment-empty-lines is t.
>
>   bug 2: this line now does not indent consistently with the
> rest of emacs.
> ===
>
> comment-dwim:
>
> ===
> # x
>
> # bug 1: the line above now does not get commented even if
> # comment-empty-lines is t.
>
>   # bug 2: this line now does not indent consistently with the
> # rest of emacs.
> ===

Both fixed.

>   bug 3: outside of org with filladapt turned OFF, filling this
> paragraph does not
> indent it.  also auto-fill
> indents unlike the rest of emacs.  ret tab is ok.

Fixed.

> #bug 4: this paragraph now gets exported in HTML subtree
> #export, which will likely surprise many people who formerly
> #used "#" comments instead of "# " comments and don't
> #carefully check all output.  they might
> #even publish private information automatically without
> #realizing it using old files that they forgot or did not
> #know to convert.

This has been announced in 7.9 changes.

> #bug 5: filling this paragraph with "===" on the following
> #line will fill the ===, unlike the rest of emacs with
> #filladapt turned ON.  we are supposed to not use filladapt
> #with org.  therefore, how do you emulate the filladapt
> #behavior so that there is consistency between emacs and
> #org?

I don't know filladapt.el. I've done my homework, though, and looked at
the file.

If you want to use filladapt.el, you'll have to tweak
`filladapt-token-*' variables. If you come up with a working setup,
please put it on org-hacks.org as some users may appreciate it.

For example, `cc-mode' does it in `c-setup-filladapt' function.

> Bug 6: what does the Org-specific commenting do?  i was not
> able to determine that from the docstring to
> org-comment-or-uncomment-region.  maybe update docstring
> would help others trying to find out why commenting works
> differently in org from the rest of emacs?

I don't think such explanations belong to
`org-comment-or-uncomment-region' docstring. Though, I have dropped
a note in org.el:

   Org comments syntax is quite complex. It requires the entire line to
   be just a comment. Also, even with the right syntax at the beginning
   of line, some some elements (i.e. verse-block or example-block) don't
   accept comments. Usual Emacs comment commands cannot cope with those
   requirements. Therefore, Org replaces them.

   Org still relies on `comment-dwim', but cannot trust
   `comment-only-p'. So, `comment-region-function' and
   `uncomment-region-function' both point
   to`org-comment-or-uncomment-region'. Eventually, `org-insert-comment'
   takes care of insertion of comments at the beginning of line.

I hope it is clearer now.

Thanks for the detailed report.


Regards,

-- 
Nicolas Goaziou

Re: bugs in commenting and filling

[Samuel Wales]

On 8/28/12, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
>> #bug 4: this paragraph now gets exported in HTML subtree
>> #export, which will likely surprise many people who formerly
>> #used "#" comments instead of "# " comments and don't
>> #carefully check all output.  they might
>> #even publish private information automatically without
>> #realizing it using old files that they forgot or did not
>> #know to convert.
>
> This has been announced in 7.9 changes.

As a user, what is the best way in both the old and new exporters to
remove #[^+] lines on export?  Flush lines in one of the hooks?  Or is
there a setting?

Or error if there are any such lines in the exported subtree.  (I
always export subtrees.)  Is this possible?

>> #bug 5: filling this paragraph with "===" on the following
>> #line will fill the ===, unlike the rest of emacs with
>> #filladapt turned ON.  we are supposed to not use filladapt
>> #with org.  therefore, how do you emulate the filladapt
>> #behavior so that there is consistency between emacs and
>> #org?
>
> I don't know filladapt.el. I've done my homework, though, and looked at
> the file.
>
> If you want to use filladapt.el, you'll have to tweak
> `filladapt-token-*' variables. If you come up with a working setup,
> please put it on org-hacks.org as some users may appreciate it.
>
> For example, `cc-mode' does it in `c-setup-filladapt' function.

filladapt worked as it does in the rest of Emacs until pretty
recently, but it stopped working (error) when Org changed filling.

This bug refers to how Org without filladapt works.

Are you suggesting getting it to work again, then fixing this bug?  My
concern is that further changes in Org might make it not work again.

The alternative is to make the Org behavior work as it used to with filladapt.

> I hope it is clearer now.

Yes, thanks for explaining that it is for comment and verse blocks.

> Thanks for the detailed report.

Thanks for addressing the bugs.

Samuel

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

Re: bugs in commenting and filling

[Nicolas Goaziou]

Hello,

Samuel Wales <samologist@gmail.com> writes:

> On 8/28/12, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
>>> #bug 4: this paragraph now gets exported in HTML subtree
>>> #export, which will likely surprise many people who formerly
>>> #used "#" comments instead of "# " comments and don't
>>> #carefully check all output.  they might
>>> #even publish private information automatically without
>>> #realizing it using old files that they forgot or did not
>>> #know to convert.
>>
>> This has been announced in 7.9 changes.
>
> As a user, what is the best way in both the old and new exporters to
> remove #[^+] lines on export?  Flush lines in one of the hooks?  Or is
> there a setting?

You can flush such lines in a hook:

#+begin_src emacs-lisp
(defun my-flush-old-comment-syntax (backend)
  (while (re-search-forward "^#[^ \t+]" nil t)
    (when (memq (org-element-type (org-element-at-point))
                '(paragraph verse-block))
      (delete-region (line-beginning-position)
                     (progn (forward-line) (point))))))

(add-hook 'org-export-before-parsing-hook 'my-flush-old-comment-syntax)
#+end_src


> Or error if there are any such lines in the exported subtree.  (I
> always export subtrees.)  Is this possible?

For a warning, you may want to have something like:

#+begin_src emacs-lisp
(defun my-old-comment-syntax-warning (backend)
  (when (re-search-forward "^#[^ \t+]" nil t)
    (or (yes-or-no-p "Document may contain old-style comment syntax.  Still proceed? ")
        (error "Export aborted"))))

(add-hook 'org-export-before-parsing-hook 'my-old-comment-syntax-warning)
#+end_src

>>> #bug 5: filling this paragraph with "===" on the following
>>> #line will fill the ===, unlike the rest of emacs with
>>> #filladapt turned ON.  we are supposed to not use filladapt
>>> #with org.  therefore, how do you emulate the filladapt
>>> #behavior so that there is consistency between emacs and
>>> #org?
>>
>> I don't know filladapt.el. I've done my homework, though, and looked at
>> the file.
>>
>> If you want to use filladapt.el, you'll have to tweak
>> `filladapt-token-*' variables. If you come up with a working setup,
>> please put it on org-hacks.org as some users may appreciate it.
>>
>> For example, `cc-mode' does it in `c-setup-filladapt' function.
>
> filladapt worked as it does in the rest of Emacs until pretty
> recently, but it stopped working (error) when Org changed filling.

If the error, which you haven't reported yet, happens when using
filladapt, then filladapt has to be tweaked.

> This bug refers to how Org without filladapt works.
>
> Are you suggesting getting it to work again, then fixing this bug?  My
> concern is that further changes in Org might make it not work again.
>
> The alternative is to make the Org behavior work as it used to with
> filladapt.

I am probably misunderstanding "bug 5". May you describe it again along
with both the expected and actual behaviour in the situation?


Regards,

-- 
Nicolas Goaziou

Re: bugs in commenting and filling

[Samuel Wales]

On 8/30/12, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> #+begin_src emacs-lisp
> (defun my-flush-old-comment-syntax (backend)

Thanks.  I like your yes or no p idea.

> I am probably misunderstanding "bug 5". May you describe it again along
> with both the expected and actual behaviour in the situation?

It works now.

Samuel

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

Re: bugs in commenting and filling

[Samuel Wales]

What hook in the old exporter would be the closest equivalent?

> (add-hook 'org-export-before-parsing-hook 'my-flush-old-comment-syntax)

Thanks.

Samuel

Re: bugs in commenting and filling

[Nicolas Goaziou]

Hello,

Samuel Wales <samologist@gmail.com> writes:

> What hook in the old exporter would be the closest equivalent?
>
>> (add-hook 'org-export-before-parsing-hook 'my-flush-old-comment-syntax)

Not equivalent, but close enough: `org-export-preprocess-hook'.


Regards,

-- 
Nicolas Goaziou