* [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).