emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* patch to change org-adapt-indentation customization documentation
@ 2020-11-17 13:22 Greg Minshall
  2020-11-17 14:08 ` Robert Pluim
  0 siblings, 1 reply; 6+ messages in thread
From: Greg Minshall @ 2020-11-17 13:22 UTC (permalink / raw)
  To: Org-mode

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.

diff --git a/lisp/org.el b/lisp/org.el
index 2b50f94ee..5bb48c2fd 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1605,10 +1605,10 @@ level-dependent indentation in a virtual way, i.e. at display
 time in Emacs."
   :group 'org-edit-structure
   :type '(choice
-         (const :tag "Adapt indentation for all lines" t)
-         (const :tag "Adapt indentation for headline data lines"
+         (const :tag "(t) Adapt indentation for all lines" t)
+         (const :tag "('headline-data) Adapt indentation for headline data lines"
                 'headline-data)
-         (const :tag "Do not adapt indentation at all" nil))
+         (const :tag "(nil) Do not adapt indentation at all" nil))
   :safe #'booleanp)

 (defvaralias 'org-special-ctrl-a 'org-special-ctrl-a/e)


^ permalink raw reply related	[flat|nested] 6+ messages in thread

* Re: patch to change org-adapt-indentation customization documentation
  2020-11-17 13:22 patch to change org-adapt-indentation customization documentation Greg Minshall
@ 2020-11-17 14:08 ` Robert Pluim
  2020-11-17 14:20   ` Greg Minshall
  0 siblings, 1 reply; 6+ messages in thread
From: Robert Pluim @ 2020-11-17 14:08 UTC (permalink / raw)
  To: Greg Minshall; +Cc: Org-mode

Greg Minshall <minshall@umich.edu> 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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: patch to change org-adapt-indentation customization documentation
  2020-11-17 14:08 ` Robert Pluim
@ 2020-11-17 14:20   ` Greg Minshall
  2020-11-18  9:49     ` Robert Pluim
  0 siblings, 1 reply; 6+ messages in thread
From: Greg Minshall @ 2020-11-17 14:20 UTC (permalink / raw)
  To: Robert Pluim; +Cc: Org-mode

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]


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: patch to change org-adapt-indentation customization documentation
  2020-11-17 14:20   ` Greg Minshall
@ 2020-11-18  9:49     ` Robert Pluim
  2020-11-18 12:13       ` Greg Minshall
  0 siblings, 1 reply; 6+ messages in thread
From: Robert Pluim @ 2020-11-18  9:49 UTC (permalink / raw)
  To: Greg Minshall; +Cc: Org-mode

Greg Minshall <minshall@umich.edu> 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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: patch to change org-adapt-indentation customization documentation
  2020-11-18  9:49     ` Robert Pluim
@ 2020-11-18 12:13       ` Greg Minshall
  2020-11-19  4:05         ` Kyle Meyer
  0 siblings, 1 reply; 6+ messages in thread
From: Greg Minshall @ 2020-11-18 12:13 UTC (permalink / raw)
  To: Robert Pluim; +Cc: Org-mode

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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: patch to change org-adapt-indentation customization documentation
  2020-11-18 12:13       ` Greg Minshall
@ 2020-11-19  4:05         ` Kyle Meyer
  0 siblings, 0 replies; 6+ messages in thread
From: Kyle Meyer @ 2020-11-19  4:05 UTC (permalink / raw)
  To: Greg Minshall; +Cc: Robert Pluim, Org-mode

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



^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2020-11-19  4:06 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-17 13:22 patch to change org-adapt-indentation customization documentation Greg Minshall
2020-11-17 14:08 ` Robert Pluim
2020-11-17 14:20   ` Greg Minshall
2020-11-18  9:49     ` Robert Pluim
2020-11-18 12:13       ` Greg Minshall
2020-11-19  4:05         ` Kyle Meyer

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