Re: [O] [PATCH] Change to org-src-preserve-indentation documentation

[John Hendy]

On Sun, Feb 2, 2014 at 3:35 PM, Nicolas Goaziou <address@hidden> wrote:
> Hello,
>
> John Hendy <address@hidden> 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.

>> address@hidden 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