[PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Valentin Wüstholz]

[-- Attachment #1: Type: text/plain, Size: 319 bytes --]

Hi,

lines in example blocks are currently indented like the surrounding
begin and end delimiters. ¨This works fine unless, you want to indent
some lines manually; in this case, auto-indenting the buffer reverts
the manual indentation. This patch should prevent this from happening.

Best regards,

Valentin

[-- Attachment #2: org.el.patch.txt --]
[-- Type: text/plain, Size: 1047 bytes --]

diff --git a/lisp/org.el b/lisp/org.el
index 11eaf78..428804d 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -19460,10 +19460,14 @@ If point is in an inline task, mark that task instead."
       (save-excursion
 	(re-search-backward "^[ \t]*#\\+begin_\\([a-z]+\\)" nil t))
       (setq column
-	    (if (equal (downcase (match-string 1)) "src")
-		;; src blocks: let `org-edit-src-exit' handle them
-		(org-get-indentation)
-	      (org-get-indentation (match-string 0)))))
+            (cond ((equal (downcase (match-string 1)) "src")
+                   ;; src blocks: let `org-edit-src-exit' handle them
+                   (org-get-indentation))
+                  ((equal (downcase (match-string 1)) "example")
+                   (max (org-get-indentation) (org-get-indentation (match-string 0))))
+                  (t
+                   (org-get-indentation (match-string 0)))
+                  )))
      ;; This line has nothing special, look at the previous relevant
      ;; line to compute indentation
      (t

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Nicolas Goaziou]

Hello,

Valentin Wüstholz <wuestholz@gmail.com> writes:

> lines in example blocks are currently indented like the surrounding
> begin and end delimiters. ¨This works fine unless, you want to indent
> some lines manually;

You may use colons instead. They are meant for this task. I.e.:

: some text
:     ^

> in this case, auto-indenting the buffer reverts the manual
> indentation. This patch should prevent this from happening.

I don't think we should prevent that as it would be more hassle to cope
with the new behaviour than doing it with colons.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Valentin Wüstholz]

Hi Nicolas.


 On Mon, Aug 8, 2011 at 10:40 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
 > Hello,
 >
 > Valentin Wüstholz <wuestholz@gmail.com> writes:
 >
 >> lines in example blocks are currently indented like the surrounding
 >> begin and end delimiters. ¨This works fine unless, you want to indent
 >> some lines manually;
 >
 > You may use colons instead. They are meant for this task. I.e.:
 >
 > : some text
 > :     ^


Colons are great for short snippets. However, blocks are far more
convenient for longer passages.


 >> in this case, auto-indenting the buffer reverts the manual
 >> indentation. This patch should prevent this from happening.
 >
 > I don't think we should prevent that as it would be more hassle to cope
 > with the new behaviour than doing it with colons.


I don't think that the behaviour is fundamentally different. Blocks
that were indented using the old behaviour will still be indented in
the same way. The new behaviour is mainly more flexible. What
potential hassle were you thinking of?

Best regards,

Valentin

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Nicolas Goaziou]

Valentin Wüstholz <wuestholz@gmail.com> writes:

> Colons are great for short snippets. However, blocks are far more
> convenient for longer passages.

That's certainly true, but I fail to see an use case for such long
passages. May I know what you do have in mind?

> What potential hassle were you thinking of?

Being left with no more literal markup automatically indented. It's not
that your idea is bad, but there could be users appreciating the current
feature.

Perhaps this could be applied to verse blocks instead.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Valentin Wüstholz]

Hi Nicolas,

thanks for the quick response.


On Tue, Aug 9, 2011 at 12:33 AM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Valentin Wüstholz <wuestholz@gmail.com> writes:
>
>> Colons are great for short snippets. However, blocks are far more
>> convenient for longer passages.
>
> That's certainly true, but I fail to see an use case for such long
> passages. May I know what you do have in mind?


Sure. At least four use cases come to my mind for this: (a) literal
console output, (b) blocks of pseudo code (can't really use SRC blocks
since there is no actual language for this), (c) blocks of source code
in experimental or little known programming languages (ditto), and (d)
sketches of mathematical proofs or computations where you don't want
to mess with LaTeX typesetting (yet). More generally, every long
passage where you would like indentation to be treated literally (not
only by an exporter, but also by the automatic indenter).


>> What potential hassle were you thinking of?
>
> Being left with no more literal markup automatically indented. It's not
> that your idea is bad, but there could be users appreciating the current
> feature.


I certainly thought about existing users, which is why by default
lines are is still indented like before. If you care about automatic
indentation, your example blocks are already indented like the
delimiters and the new behaviour keeps it just like that. If you
previously chose to indent you blocks differently, the new behaviour
will respect that decision by not messing with your indentation.


> Perhaps this could be applied to verse blocks instead.


As far as I recall verse blocks are treated somewhat differently from
example blocks by the exporter (e.g. verse vs verbatim in LaTeX).
Initially, I thought about allowing no specific language in SRC
blocks. However, this seems somewhat counterintuitive to me.

Best regards,

Valentin

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Nicolas Goaziou]

Hello,

Valentin Wüstholz <wuestholz@gmail.com> writes:

> Sure. At least four use cases come to my mind for this: (a) literal
> console output, (b) blocks of pseudo code (can't really use SRC blocks
> since there is no actual language for this), (c) blocks of source code
> in experimental or little known programming languages (ditto), and (d)
> sketches of mathematical proofs or computations where you don't want
> to mess with LaTeX typesetting (yet).

I see (even though #d sounds strange).

>>> What potential hassle were you thinking of?
>>
>> Being left with no more literal markup automatically indented. It's not
>> that your idea is bad, but there could be users appreciating the current
>> feature.
>
> I certainly thought about existing users, which is why by default
> lines are is still indented like before. If you care about automatic
> indentation, your example blocks are already indented like the
> delimiters and the new behaviour keeps it just like that. If you
> previously chose to indent you blocks differently, the new behaviour
> will respect that decision by not messing with your indentation.

Both situations are different from an user perspective.

With the current behaviour, the only annoyance you encounter is that you
cannot indent the whole buffer (or a region containing the block)
automatically. But nothing prevents you from writing (and exporting)
arbitrarily indented code. Sure, you won't get any indenting help in the
process but it's the same as in your proposal. So all you have to do is
basically refraining from using a global indentation tool.

In your proposal, you still can write text with no indenting help. You
can now indent the whole buffer, too. But there's one major problem.
Suppose that you paste some badly indented text (from an external
source) into an example block. You want to indent it properly... but
it's now impossible. You have to fix indentation manually, line by line.

To sum it up, in the first case, you only loose the ability to indent
the whole buffer in one go (which isn't as bad as it sounds, since you
can achieve that differently). In the second case, you get limited in
your actions as you completely loose the ability to indent examples.

I still think that's not fair.

>> Perhaps this could be applied to verse blocks instead.
>
> As far as I recall verse blocks are treated somewhat differently from
> example blocks by the exporter (e.g. verse vs verbatim in LaTeX).

Indeed, but I think verses are closer to free text than examples and, as
such, may not be subject to automatic indentation.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Valentin Wüstholz]

Hi Nicolas.


On Tue, Aug 9, 2011 at 11:18 AM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Hello,
>
> Valentin Wüstholz <wuestholz@gmail.com> writes:
>
>> Sure. At least four use cases come to my mind for this: (a) literal
>> console output, (b) blocks of pseudo code (can't really use SRC blocks
>> since there is no actual language for this), (c) blocks of source code
>> in experimental or little known programming languages (ditto), and (d)
>> sketches of mathematical proofs or computations where you don't want
>> to mess with LaTeX typesetting (yet).
>
> I see (even though #d sounds strange).
>
>>>> What potential hassle were you thinking of?
>>>
>>> Being left with no more literal markup automatically indented. It's not
>>> that your idea is bad, but there could be users appreciating the current
>>> feature.
>>
>> I certainly thought about existing users, which is why by default
>> lines are is still indented like before. If you care about automatic
>> indentation, your example blocks are already indented like the
>> delimiters and the new behaviour keeps it just like that. If you
>> previously chose to indent you blocks differently, the new behaviour
>> will respect that decision by not messing with your indentation.
>
> Both situations are different from an user perspective.
>
> With the current behaviour, the only annoyance you encounter is that you
> cannot indent the whole buffer (or a region containing the block)
> automatically. But nothing prevents you from writing (and exporting)
> arbitrarily indented code. Sure, you won't get any indenting help in the
> process but it's the same as in your proposal. So all you have to do is
> basically refraining from using a global indentation tool.
>
> In your proposal, you still can write text with no indenting help. You
> can now indent the whole buffer, too. But there's one major problem.
> Suppose that you paste some badly indented text (from an external
> source) into an example block. You want to indent it properly... but
> it's now impossible. You have to fix indentation manually, line by line.


I would argue, that most of the time when you copy something from an
external source into an example block, you want to preserve the
indentation and formatting. At least that's my understanding of what
/literal/ examples should give you. Besides, you don't need to fix
each line separately: simply removing the indentation and
auto-indenting the block will get you the desired results.

I fully agree that that's a slight change in behaviour. However, there
are simple ways of fixing the issue you pointed out /once/ (when you
past the text), whereas at the moment the default indentation is
forced on you /every time/ you want to indent a line, region or
buffer.

Obviously, this is mainly my personal view as someone that relies on
auto-indentation quite heavily. I would love to hear how other people
feel about this. If too many people don't like the new behaviour, one
could still consider adding an optional switch (like -n in SRC
blocks).


> To sum it up, in the first case, you only loose the ability to indent
> the whole buffer in one go (which isn't as bad as it sounds, since you
> can achieve that differently).


How else would you be able to achieve that?


> In the second case, you get limited in your actions as you completely loose the ability to indent examples.


I don't see why you would lose the ability to indent examples. When
you write inside the block, each line will be auto-indented just like
before. Only the lines that were manually indented further to the
right, will not be reset to the default indentation. In that sense,
you become more flexible in how your example blocks can be indented.


>>> Perhaps this could be applied to verse blocks instead.
>>
>> As far as I recall verse blocks are treated somewhat differently from
>> example blocks by the exporter (e.g. verse vs verbatim in LaTeX).
>
> Indeed, but I think verses are closer to free text than examples and, as
> such, may not be subject to automatic indentation.


I might be wrong, but I believe that at least in LaTeX indentation in
verse blocks is not taken into account. This seems reasonable since
they are not typeset in a monospaced font.

Best regards,

Valentin

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Nicolas Goaziou]

Valentin Wüstholz <wuestholz@gmail.com> writes:

> At least that's my understanding of what /literal/ examples should
> give you. Besides, you don't need to fix each line separately: simply
> removing the indentation and auto-indenting the block will get you the
> desired results.

Ah, true. I hadn't thought about that. I guess it's not that bad then.

> I would love to hear how other people feel about this.

Same here. I don't use such blocks very often after all.

Meanwhile, could you please reformat a bit your patch (no more than 80
columns, no parents on their own line), add a commit message followed
by TINYCHANGE (unless you have signed FSF papers already) and use git
format-patch for the output?

>> To sum it up, in the first case, you only loose the ability to indent
>> the whole buffer in one go (which isn't as bad as it sounds, since you
>> can achieve that differently).
>
> How else would you be able to achieve that?

You may still indent regions without examples blocks, you can also
indent automatically each line you're writing.

I rarely indent globally buffers I wrote.

> I might be wrong, but I believe that at least in LaTeX indentation in
> verse blocks is not taken into account. This seems reasonable since
> they are not typeset in a monospaced font.

Actually indentation is partially taken into account. Some \hspace*{1cm}
are added. On the other hand, HTML enforces indentation with the help of
&nbsp;.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Valentin Wüstholz]

[-- Attachment #1: Type: text/plain, Size: 1438 bytes --]

Hi Nicolas.


On Tue, Aug 9, 2011 at 3:21 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
>> I would love to hear how other people feel about this.
>
> Same here. I don't use such blocks very often after all.
>
> Meanwhile, could you please reformat a bit your patch (no more than 80
> columns, no parents on their own line), add a commit message followed
> by TINYCHANGE (unless you have signed FSF papers already) and use git
> format-patch for the output?


Sure. I have attached the output.


>>> To sum it up, in the first case, you only loose the ability to indent
>>> the whole buffer in one go (which isn't as bad as it sounds, since you
>>> can achieve that differently).
>>
>> How else would you be able to achieve that?
>
> You may still indent regions without examples blocks, you can also
> indent automatically each line you're writing.


True, but that gets quite tedious once you have more than two or three
blocks in your file.


>> I might be wrong, but I believe that at least in LaTeX indentation in
>> verse blocks is not taken into account. This seems reasonable since
>> they are not typeset in a monospaced font.
>
> Actually indentation is partially taken into account. Some \hspace*{1cm}
> are added. On the other hand, HTML enforces indentation with the help of
> &nbsp;.


Your right, it seems that org-mode somehow deals with it, even though
LaTeX doesn't quite support it natively.

Best regards,

Valentin

[-- Attachment #2: 0001-Preserve-indentation-of-explicitly-indented-lines-in.patch.txt --]
[-- Type: text/plain, Size: 1744 bytes --]

From c64f1b607d937c6484dfc18110125b1287175ac4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20W=FCstholz?= <wuestholz@gmail.com>
Date: Tue, 9 Aug 2011 21:28:56 +0200
Subject: [PATCH] Preserve indentation of explicitly indented lines in example blocks

* lisp/org.el (org-indent-line-function): Made the way in which example blocks are
  indented more flexible.

Before: Lines in example blocks were indented like the surrounding begin and end
delimiters.
After: By default, lines in example blocks are indented like the surrounding begin and end
delimiters, unless the user explicitly indents them differently.

TINYCHANGE
---
 lisp/org.el |   12 ++++++++----
 1 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index ba7f049..d8f1d2a 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -19460,10 +19460,14 @@ If point is in an inline task, mark that task instead."
       (save-excursion
 	(re-search-backward "^[ \t]*#\\+begin_\\([a-z]+\\)" nil t))
       (setq column
-	    (if (equal (downcase (match-string 1)) "src")
-		;; src blocks: let `org-edit-src-exit' handle them
-		(org-get-indentation)
-	      (org-get-indentation (match-string 0)))))
+            (cond ((equal (downcase (match-string 1)) "src")
+                   ;; src blocks: let `org-edit-src-exit' handle them
+                   (org-get-indentation))
+                  ((equal (downcase (match-string 1)) "example")
+                   (max (org-get-indentation)
+			(org-get-indentation (match-string 0))))
+                  (t
+                   (org-get-indentation (match-string 0))))))
      ;; This line has nothing special, look at the previous relevant
      ;; line to compute indentation
      (t
-- 
1.7.4.msysgit.0

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Nicolas Goaziou]

Hello,

Valentin Wüstholz <wuestholz@gmail.com> writes:

> Sure. I have attached the output.

Thank you. I have applied it to master.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Bastien]

Hi Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Valentin Wüstholz <wuestholz@gmail.com> writes:
>
>> Sure. I have attached the output.
>
> Thank you. I have applied it to master.

Thanks for taking care of applying this patch.

-- 
 Bastien

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Bastien]

Hi Valentin,

Valentin Wüstholz <wuestholz@gmail.com> writes:

>> Meanwhile, could you please reformat a bit your patch (no more than 80
>> columns, no parents on their own line), add a commit message followed
>> by TINYCHANGE (unless you have signed FSF papers already) and use git
>> format-patch for the output?
>
> Sure. I have attached the output.

Thanks for making the effort of reformatting patches this way.  With 
so many patches coming in, it's really important that everyone tries to
stick to immediately-applicable patches.

> From c64f1b607d937c6484dfc18110125b1287175ac4 Mon Sep 17 00:00:00 2001
> From: =?UTF-8?q?Valentin=20W=FCstholz?= <wuestholz@gmail.com>
> Date: Tue, 9 Aug 2011 21:28:56 +0200
> Subject: [PATCH] Preserve indentation of explicitly indented lines in example blocks
>
> * lisp/org.el (org-indent-line-function): Made the way in which example blocks are
>   indented more flexible.

This line a bit long and should be something like:

> * lisp/org.el (org-indent-line-function): Made the way in which
>   example blocks are indented more flexible.

Use M-q in change-log-mode on the ChangeLog to fill the region
correctly.

> Before: Lines in example blocks were indented like the surrounding begin and end
> delimiters.
> After: By default, lines in example blocks are indented like the surrounding begin and end
> delimiters, unless the user explicitly indents them differently.

Here again, I prefer <80 characters lines, but that's less important
than the ChangeLog entry.

Thanks,

-- 
 Bastien

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Valentin Wüstholz]

Hi Bastien,

thanks for the comments. I'll certainly keep that in mind for future
patches. Maybe that's something that could be added to the
corresponding worg page (http://orgmode.org/worg/org-contribute.html).

Best regards,

Valentin


On Tue, Aug 16, 2011 at 9:18 PM, Bastien <bzg@altern.org> wrote:
> Hi Valentin,
>
> Valentin Wüstholz <wuestholz@gmail.com> writes:
>
>>> Meanwhile, could you please reformat a bit your patch (no more than 80
>>> columns, no parents on their own line), add a commit message followed
>>> by TINYCHANGE (unless you have signed FSF papers already) and use git
>>> format-patch for the output?
>>
>> Sure. I have attached the output.
>
> Thanks for making the effort of reformatting patches this way.  With
> so many patches coming in, it's really important that everyone tries to
> stick to immediately-applicable patches.
>
>> From c64f1b607d937c6484dfc18110125b1287175ac4 Mon Sep 17 00:00:00 2001
>> From: =?UTF-8?q?Valentin=20W=FCstholz?= <wuestholz@gmail.com>
>> Date: Tue, 9 Aug 2011 21:28:56 +0200
>> Subject: [PATCH] Preserve indentation of explicitly indented lines in example blocks
>>
>> * lisp/org.el (org-indent-line-function): Made the way in which example blocks are
>>   indented more flexible.
>
> This line a bit long and should be something like:
>
>> * lisp/org.el (org-indent-line-function): Made the way in which
>>   example blocks are indented more flexible.
>
> Use M-q in change-log-mode on the ChangeLog to fill the region
> correctly.
>
>> Before: Lines in example blocks were indented like the surrounding begin and end
>> delimiters.
>> After: By default, lines in example blocks are indented like the surrounding begin and end
>> delimiters, unless the user explicitly indents them differently.
>
> Here again, I prefer <80 characters lines, but that's less important
> than the ChangeLog entry.
>
> Thanks,
>
> --
>  Bastien
>

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Bastien]

Hi Valentin,

Valentin Wüstholz <wuestholz@gmail.com> writes:

> thanks for the comments. I'll certainly keep that in mind for future
> patches. 

Thanks :)

> Maybe that's something that could be added to the
> corresponding worg page (http://orgmode.org/worg/org-contribute.html).

This is already described here:

  http://orgmode.org/worg/org-contribute.html#sec-5

Feel free to make this page even clearer!

-- 
 Bastien

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Valentin Wüstholz]

Hi Bastien.


On Wed, Aug 17, 2011 at 11:40 AM, Bastien <bzg@altern.org> wrote:
>> Maybe that's something that could be added to the
>> corresponding worg page (http://orgmode.org/worg/org-contribute.html).
>
> This is already described here:
>
>  http://orgmode.org/worg/org-contribute.html#sec-5
>
> Feel free to make this page even clearer!


I was thinking of the the 80 character line limit for both code and
commit messages, which doesn't seem to be in there. It might also make
sense to link to some style guide for Emacs Lisp (e.g.,
http://www.gnu.org/software/emacs/elisp/html_node/Coding-Conventions.html),
that developers should adhere to. If you agree, I could commit those
additions to worg.

Best regards,

Valentin

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Bastien]

Hi Valentin,

Valentin Wüstholz <wuestholz@gmail.com> writes:

> I was thinking of the the 80 character line limit for both code and
> commit messages, which doesn't seem to be in there. It might also make
> sense to link to some style guide for Emacs Lisp (e.g.,
> http://www.gnu.org/software/emacs/elisp/html_node/Coding-Conventions.html),
> that developers should adhere to. If you agree, I could commit those
> additions to worg.

I added a section pointing to this link in org-contribute.org.

It will be online as soon as Worg gets published fine again.

Thanks,

-- 
 Bastien

Re: [PATCH] org.el: Preserve indentation of manually indented lines in example blocks.

[Valentin Wüstholz]

On Thu, Aug 18, 2011 at 6:44 PM, Bastien <bzg@altern.org> wrote:
> Valentin Wüstholz <wuestholz@gmail.com> writes:
>
>> I was thinking of the the 80 character line limit for both code and
>> commit messages, which doesn't seem to be in there. It might also make
>> sense to link to some style guide for Emacs Lisp (e.g.,
>> http://www.gnu.org/software/emacs/elisp/html_node/Coding-Conventions.html),
>> that developers should adhere to. If you agree, I could commit those
>> additions to worg.
>
> I added a section pointing to this link in org-contribute.org.
>
> It will be online as soon as Worg gets published fine again.

Great!

Thanks,

Valentin