Org-mode mailing list
 help / color / mirror / Atom feed
From: Kyle Meyer <kyle@kyleam.com>
To: Greg Minshall <minshall@umich.edu>
Cc: Robert Pluim <rpluim@gmail.com>, Org-mode <emacs-orgmode@gnu.org>
Subject: Re: patch to change org-adapt-indentation customization documentation
Date: Wed, 18 Nov 2020 23:05:41 -0500
Message-ID: <87r1oq0z56.fsf@kyleam.com> (raw)
In-Reply-To: <926418.1605701588@apollo2.minshall.org>

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



      reply	other threads:[~2020-11-19  4:06 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-11-17 13:22 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 [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://orgmode.org

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87r1oq0z56.fsf@kyleam.com \
    --to=kyle@kyleam.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=minshall@umich.edu \
    --cc=rpluim@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Org-mode mailing list

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://orgmode.org/list/0 list/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 list list/ https://orgmode.org/list \
		emacs-orgmode@gnu.org
	public-inbox-index list

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.yhetil.org/yhetil.emacs.orgmode
	nntp://news.gmane.io/gmane.emacs.orgmode


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git