* [PATCH] Change to org-src-preserve-indentation documentation
@ 2014-02-02 16:06 John Hendy
2014-02-02 21:35 ` Nicolas Goaziou
0 siblings, 1 reply; 6+ messages in thread
From: John Hendy @ 2014-02-02 16:06 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 888 bytes --]
Greetings,
Per some other discussions on the mentioned variable, I added a bit
more information to org.texi to help other users find it's
documentation in the manual.
Old description:
This variable is especially useful for tangling languages such as
Python, in which whitespace indentation in the output is critical.
New description:
By default, the value is nil, which means that whitespace characters will be
collapsed upon exporting/tangling, according to the value of
org-edit-src-content-indentation.
If set to t, code blocks will be exported/tangled with whitespace
preserved, exactly as they
appear in the org buffer. This variable is especially useful for
tangling languages such as
Python, in which whitespace indentation in the output is critical.
Let me know if I should change anything; happy to adjust to a better
explanation and re-create a patch.
Best regards,
John
[-- Attachment #2: 0001-Update-org.texi-documentation-for-org-src-preserve-i.patch --]
[-- Type: text/x-patch, Size: 1317 bytes --]
From e2710a3d5b620152ea7ab81489cc20cf23747b16 Mon Sep 17 00:00:00 2001
From: John Henderson <jw.hendy@gmail.com>
Date: Fri, 31 Jan 2014 15:29:47 -0600
Subject: [PATCH] Update org.texi documentation for
org-src-preserve-indentation
---
doc/org.texi | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/doc/org.texi b/doc/org.texi
index 9c7a6a7..666282c 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13798,7 +13798,11 @@ can be used to map arbitrary language names to existing major modes.
@item org-src-window-setup
Controls the way Emacs windows are rearranged when the edit buffer is created.
@item org-src-preserve-indentation
-This variable is especially useful for tangling languages such as
+By default, the value is @code{nil}, which means that whitespace characters will be
+collapsed upon exporting/tangling, according to the value of
+@code{org-edit-src-content-indentation}. If set to @code{t}, code
+blocks will be exported/tangled with whitespace preserved, exactly as they
+appear in the org buffer. This variable is especially useful for tangling languages such as
Python, in which whitespace indentation in the output is critical.
@item org-src-ask-before-returning-to-edit-buffer
By default, Org will ask before returning to an open edit buffer. Set this
--
1.8.5.3
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] Change to org-src-preserve-indentation documentation
2014-02-02 16:06 [PATCH] Change to org-src-preserve-indentation documentation John Hendy
@ 2014-02-02 21:35 ` Nicolas Goaziou
2014-02-03 23:12 ` John Hendy
2014-03-12 1:26 ` John Hendy
0 siblings, 2 replies; 6+ messages in thread
From: Nicolas Goaziou @ 2014-02-02 21:35 UTC (permalink / raw)
To: John Hendy; +Cc: emacs-orgmode
Hello,
John Hendy <jw.hendy@gmail.com> writes:
> Per some other discussions on the mentioned variable, I added a bit
> more information to org.texi to help other users find it's
> documentation in the manual.
Thank you for the patch. It is certainly better than what we have
actually.
Some comments follow.
> -This variable is especially useful for tangling languages such as
> +By default, the value is @code{nil}, which means that whitespace characters will be
> +collapsed upon exporting/tangling, according to the value of
I think "exporting or tangling" is better than "exporting/tangling", but
I'm no native speaker.
Also, I'm not sure if "collapsed" is very clear. During export, when the
source block is evaluated, it is removed from the buffer and, maybe,
inserted back. At this point, if `org-src-preserve-indentation' is nil,
every line is indented back to the same column as it was before. Tabs
can appear in the process.
If `org-src-preserve-indentation' is nil, global indentation is lost,
but the local one is preserved. Since no indentation happens, tabs
cannot appear in the process.
> +@code{org-edit-src-content-indentation}. If set to @code{t}, code
In Texinfo, sentences have to end with two spaces. Also, the variable
doesn't need to be set to the symbol t, as any value but nil will
achieve the same result. So the sentence could start with something
like :
When non-nil, code blocks...
> +blocks will be exported/tangled with whitespace preserved, exactly as they
exported or tangled, maybe
> +appear in the org buffer. This variable is especially useful for
> tangling languages such as
It should be Org, not org. And two spaces are required.
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Change to org-src-preserve-indentation documentation
2014-02-02 21:35 ` Nicolas Goaziou
@ 2014-02-03 23:12 ` John Hendy
2014-02-04 8:26 ` Sebastien Vauban
2014-03-12 1:26 ` John Hendy
1 sibling, 1 reply; 6+ messages in thread
From: John Hendy @ 2014-02-03 23:12 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: emacs-orgmode
On Sun, Feb 2, 2014 at 3:35 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Hello,
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> Per some other discussions on the mentioned variable, I added a bit
>> more information to org.texi to help other users find it's
>> documentation in the manual.
>
> Thank you for the patch. It is certainly better than what we have
> actually.
>
> Some comments follow.
>
>> -This variable is especially useful for tangling languages such as
>> +By default, the value is @code{nil}, which means that whitespace characters will be
>> +collapsed upon exporting/tangling, according to the value of
>
> I think "exporting or tangling" is better than "exporting/tangling", but
> I'm no native speaker.
No problem, and as a native speaker, I'd say yours is more formal/clearer.
>
> Also, I'm not sure if "collapsed" is very clear. During export, when the
> source block is evaluated, it is removed from the buffer and, maybe,
> inserted back. At this point, if `org-src-preserve-indentation' is nil,
> every line is indented back to the same column as it was before. Tabs
> can appear in the process.
>
> If `org-src-preserve-indentation' is nil, global indentation is lost,
> but the local one is preserved. Since no indentation happens, tabs
> cannot appear in the process.
>
Thanks for the explanation. This was my attempt to describe what
usually happens, but I wasn't sure. I know from reading some other
documentation, it mentioned the variable
org-src-edit-content-indentation, which seemed like it would
"collapse" a bunch of whitespace down to a set value, but maybe that's
only if one uses the C-c ' shortcut to edit? Anyway, I'll just remove
that bit.
>> +@code{org-edit-src-content-indentation}. If set to @code{t}, code
>
> In Texinfo, sentences have to end with two spaces. Also, the variable
> doesn't need to be set to the symbol t, as any value but nil will
> achieve the same result. So the sentence could start with something
> like :
>
> When non-nil, code blocks...
>
Good to know about two spaces! I had no idea. Out of curiosity is that
file generated from a .org file? Or is that the main documentation
everyone edits/writes in?
Good to know regarding the value of =t= as well. Does a numeric value
do anything, or is it simply a binary variable (non-nil vs. anything
else). For my personal preference, I don't understand the idea of a
variable that acts binary yet takes any number of values :)
>> +blocks will be exported/tangled with whitespace preserved, exactly as they
>
> exported or tangled, maybe
>
Yup.
>> +appear in the org buffer. This variable is especially useful for
>> tangling languages such as
>
> It should be Org, not org. And two spaces are required.
>
Got it. I thought the same thing, but swear I just ran into that
("org" vs. "Org") recently and followed the convention. Grepping files
in org.git and worg.git revealed only a handful of instances where
lower case "org" is used, so I must have been imagining or recalling
something from the mailing list vs. official docs.
Thanks for the feedback,
John
>
> Regards,
>
> --
> Nicolas Goaziou
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Change to org-src-preserve-indentation documentation
2014-02-03 23:12 ` John Hendy
@ 2014-02-04 8:26 ` Sebastien Vauban
0 siblings, 0 replies; 6+ messages in thread
From: Sebastien Vauban @ 2014-02-04 8:26 UTC (permalink / raw)
To: emacs-orgmode-mXXj517/zsQ
John Hendy wrote:
>> It should be Org, not org. And two spaces are required.
>
> Got it. I thought the same thing, but swear I just ran into that
> ("org" vs. "Org") recently and followed the convention. Grepping files
> in org.git and worg.git revealed only a handful of instances where
> lower case "org" is used, so I must have been imagining or recalling
> something from the mailing list vs. official docs.
If we follow the convention of Emacs manuals [1], we should write "Org
mode" (first letter in upper case, no dash between Org and mode).
Best regards,
Seb
[1] "Dired buffer", "Shell mode", etc.
--
Sebastien Vauban
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Change to org-src-preserve-indentation documentation
2014-02-02 21:35 ` Nicolas Goaziou
2014-02-03 23:12 ` John Hendy
@ 2014-03-12 1:26 ` John Hendy
2014-03-12 8:01 ` Nicolas Goaziou
1 sibling, 1 reply; 6+ messages in thread
From: John Hendy @ 2014-03-12 1:26 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 637 bytes --]
On Sun, Feb 2, 2014 at 3:35 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Hello,
> Thank you for the patch. It is certainly better than what we have
> actually.
>
> Some comments follow.
>
[snip]
Thanks for the comments, and sorry for the delay in re-submitting!
Hopefully I followed your explanation; I tried to incorporate what
would be relevant in understanding the variable's behavior without
getting too caught in summarizing internals that aren't really
necessary for using the variable successfully.
Let me know if you have further suggestions on the change.
Best regards,
John
>
>
> Regards,
>
> --
> Nicolas Goaziou
[-- Attachment #2: 0001-modified-documentation-for-org-src-preserve-indentat.patch --]
[-- Type: text/x-patch, Size: 1442 bytes --]
From db2109a1fee1fe62dbfbdd0c97e8cf4f6892d74b Mon Sep 17 00:00:00 2001
From: John Henderson <jw.hendy@gmail.com>
Date: Tue, 11 Mar 2014 20:23:39 -0500
Subject: [PATCH] modified documentation for org-src-preserve-indentation
---
doc/org.texi | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/doc/org.texi b/doc/org.texi
index 7e66034..42c76b0 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13804,8 +13804,13 @@ can be used to map arbitrary language names to existing major modes.
@item org-src-window-setup
Controls the way Emacs windows are rearranged when the edit buffer is created.
@item org-src-preserve-indentation
-This variable is especially useful for tangling languages such as
-Python, in which whitespace indentation in the output is critical.
+By default, the value is @code{nil}, which means that when code blocks are
+evaluated during export or tangled, they are re-inserted into the code block,
+which may replace sequences of spaces with tab characters. When non-nil,
+whitespace in code blocks will be preserved during export or tangling,
+exactly as it appears. This variable is especially useful for tangling
+languages such as Python, in which whitespace indentation in the output is
+critical.
@item org-src-ask-before-returning-to-edit-buffer
By default, Org will ask before returning to an open edit buffer. Set this
variable to @code{nil} to switch without asking.
--
1.9.0
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] Change to org-src-preserve-indentation documentation
2014-03-12 1:26 ` John Hendy
@ 2014-03-12 8:01 ` Nicolas Goaziou
0 siblings, 0 replies; 6+ messages in thread
From: Nicolas Goaziou @ 2014-03-12 8:01 UTC (permalink / raw)
To: John Hendy; +Cc: emacs-orgmode
Hello,
John Hendy <jw.hendy@gmail.com> writes:
> Let me know if you have further suggestions on the change.
It looks good. Applied. Thank you.
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-03-12 8:00 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-02-02 16:06 [PATCH] Change to org-src-preserve-indentation documentation John Hendy
2014-02-02 21:35 ` Nicolas Goaziou
2014-02-03 23:12 ` John Hendy
2014-02-04 8:26 ` Sebastien Vauban
2014-03-12 1:26 ` John Hendy
2014-03-12 8:01 ` Nicolas Goaziou
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).