Re: patch to change org-adapt-indentation customization documentation
Greg Minshall writes: > for some reason, i was motivated to look at changing > org-adapt-indentation. i found that the help text talked about values > t, 'headline-data, and nil, but that the customization text didn't > (though, of course, it *set* those values). the following might make it > clearer. > The whole point of customize is that you shouldn't have to worry about what the actual lisp value is. The actual lisp value only matters if you directly set the value without using customize. Robert
Re: patch to change org-adapt-indentation customization documentation
Robert, > The whole point of customize is that you shouldn't have to worry about > what the actual lisp value is. The actual lisp value only matters if > you directly set the value without using customize. thanks for the response. i've included the documentation for org-adapt-indentation below. since the documentation talks about values and associated behaviors, it might be helpful to mention the values in the customization dialog. an alternative maybe would be to re-do the documentation to highlight the three customization phrases: "Adapt indentation for all lines" "Adapt indentation for headline data lines" "Do not adapt indentation at all" and not change the customization dialog? i, anyway, was very uncertain, even after several rounds, as to which customization option would give me the behavior i had read about in the documentation. cheers, Greg org-adapt-indentation is a variable defined in ‘org.el’. Its value is 'headline-data Original value was t This variable is safe as a file local variable if its value satisfies the predicate ‘booleanp’. You can customize this variable. Documentation: Non-nil means adapt indentation to outline node level. When this variable is set to t, Org assumes that you write outlines by indenting text in each node to align with the headline (after the stars). When this variable is set to ’headline-data, only adapt the indentation of the data lines right below the headline, such as planning/clock lines and property/logbook drawers. The following issues are influenced by this variable: - The indentation is increased by one space in a demotion command, and decreased by one in a promotion command. However, in the latter case, if shifting some line in the entry body would alter document structure (e.g., insert a new headline), indentation is not changed at all. - Property drawers and planning information is inserted indented when this variable is set. When nil, they will not be indented. - TAB indents a line relative to current level. The lines below a headline will be indented when this variable is set to t. Note that this is all about true indentation, by adding and removing space characters. See also "org-indent.el" which does level-dependent indentation in a virtual way, i.e. at display time in Emacs. [back]
Re: patch to change org-adapt-indentation customization documentation
Greg Minshall writes: > Robert, > >> The whole point of customize is that you shouldn't have to worry about >> what the actual lisp value is. The actual lisp value only matters if >> you directly set the value without using customize. > > thanks for the response. i've included the documentation for > org-adapt-indentation below. since the documentation talks about values > and associated behaviors, it might be helpful to mention the values in > the customization dialog. an alternative maybe would be to re-do the > documentation to highlight the three customization phrases: > > "Adapt indentation for all lines" > "Adapt indentation for headline data lines" > "Do not adapt indentation at all" > > and not change the customization dialog? > Yes, I think that would be better. > i, anyway, was very uncertain, even after several rounds, as to which > customization option would give me the behavior i had read about in the > documentation. That means the docstring is probably the thing that needs adjusting. Robert
Re: patch to change org-adapt-indentation customization documentation
hi, Robert, thanks. given that the docstring already talks about nil, t, 'headline-data ... should i eliminate those, just leaving "three" choices? > "Adapt indentation for all lines" > "Adapt indentation for headline data lines" > "Do not adapt indentation at all" or, leave mention of nil, t, 'headline-data, while trying to make clearer the binding of the longer descriptions in the docstring to the above short descriptions? i guess i see lots of emacs docstrings that talk of t, nil, etc. so, maybe it's not inappropriate for them to be in the docstring. (but, in which case, then i wonder, why not mention them also in the choices?) i'm happy to do the docstring thing. but, just wanted this clarification. cheers, Greg
Re: patch to change org-adapt-indentation customization documentation
Greg Minshall writes: > hi, Robert, > > thanks. given that the docstring already talks about nil, t, > 'headline-data ... Not related to your main point, but if you're improving the docstring anyway: 'headline-data (which is a relatively recent addition) should instead be written as `headline-data' for consistency and to avoid worrying about needing to protect it from being confusingly rendered as "’headline-data" (depending on text-quoting-style). > should i eliminate those, just leaving "three" choices? > >> "Adapt indentation for all lines" >> "Adapt indentation for headline data lines" >> "Do not adapt indentation at all" > > or, leave mention of nil, t, 'headline-data, while trying to make > clearer the binding of the longer descriptions in the docstring to the > above short descriptions? > > i guess i see lots of emacs docstrings that talk of t, nil, etc. so, > maybe it's not inappropriate for them to be in the docstring. Please leave the values in the docstring. But any rewording of docstring that you think makes the customization labels easier to link to the docstring is welcome. > (but, in which case, then i wonder, why not mention them also in the > choices?) I'm sympathetic to Robert's "you shouldn't have to worry about what the actual lisp value is" stance. But I don't actually use the customize interface, so maybe that preference just comes from my impression that I never see the value in tag labels in source code. Crude grepping in the Emacs repo suggests it's rare (at least for nil): $ git grep 'const :tag ".*nil.*" nil' '*.el' lisp/bindings.el: (const :tag "nil: No offset is displayed" nil) lisp/comint.el: :type '(choice (const :tag "nil" nil) lisp/help.el: :type '(choice (const :tag "never (nil)" nil) lisp/ps-mule.el: (const bdf-font-except-latin) (const :tag "nil" nil)) lisp/ps-print.el:(const control) (const :tag "nil" nil)) lisp/ps-print.el:(const :tag "nil" nil)) lisp/scroll-bar.el: :type '(choice (const :tag "none (nil)" nil) lisp/so-long.el:(const :tag "nil: Call so-long as normal" nil) lisp/so-long.el:(const :tag "nil: Use so-long-function as normal" nil) lisp/textmodes/tex-mode.el: :type '(radio (const :tag "Interactive (nil)" nil) $ git grep 'const :tag ".*" nil' '*.el' | wc -l 1064
