From: James Harkins <jamshark70@gmail.com>
To: Emacs-orgmode@gnu.org
Subject: Re: Visibility cycling of plain lists?
Date: Tue, 1 Jan 2013 10:13:05 +0800 [thread overview]
Message-ID: <CAFniQ7Uz_GYF13r9eE=AYQCpdVc027FZygUAmVrL-JMKNB9LFg@mail.gmail.com> (raw)
In-Reply-To: <87sj6ml2x5.fsf@bzg.ath.cx>
On Mon, Dec 31, 2012 at 10:19 PM, Bastien <bzg@altern.org> wrote:
> Hi James,
>
> James Harkins <jamshark70@gmail.com> writes:
>
>> My point exactly- neither the manual nor the docstring do anything to
>> dispel that confusion.
>
> If you do C-h v org-cycle-include-plain-lists RET you read that
> a value of t allows visibility cycling and that a value of 'integrate
> temporarily interprets list items as outline headlines.
You're right; I had forgotten to expand the docstring, so I saw only
the first line. The options are explained in subsequent paragraphs.
The only issue left, then, is the disconnect between the value menu
descriptions and the actual values. Here, I guess it would make sense
to follow the Emacs convention for documenting customize-interface
value menus, if there is such a convention. If not, this patch might
help, adding text like this after the paragraph description:
~~
Value menu options:
Never --> nil
With cursor in plain list (recommended) --> t (the default)
As children of outline headings --> integrate
~~
(I'm assuming the convention is not "don't document.")
In the org manual, it would probably be enough to add a parenthetical note:
~~
If this variable is set to 'integrate' ("As children of outline
headings" in the customize interface), plain list items will be
treated like low-level headlines.
~~
> When customizing, you can either set it to "Never", which is obvious.
>
> Or to `t', which is explained.
I differ here -- in the menu, you don't set it to "t."
> Or to the other value, which is the symbol 'integrate. This third
> value is mentioned in the docstring, and it is pretty obvious that
> it corresponds to "As children of outline headings", as there are
> no other choices.
Ah, I see. It's *obvious*. (I guess org-mode's target audience is
smarter than I am.)
I do see your point that the options are described, and I apologize
for overlooking them earlier. But, if one is using the customize
interface, then there remains a (small) bit of guesswork to connect
the documentation to what is presented in the interface, and I think
generally documentation should be there to eliminate guesswork (or at
least reduce the need for it). (That's not a specific complaint to org
-- on the SuperCollider mailing list, I'm constantly harping on method
documentation that doesn't explain the expected types of the input and
output, for the same reason -- if I have to write a short bit of test
code to figure out what the method is supposed to do, then the
documentation isn't complete.)
hjh
PS And *again* I'm bitten by the fact that I just can't get used to
mailing lists where replies are sent to individual authors as well as
the list address... sorry about that.
next prev parent reply other threads:[~2013-01-01 2:13 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-12-31 3:53 Visibility cycling of plain lists? James Harkins
2012-12-31 4:01 ` James Harkins
2012-12-31 9:36 ` Bastien
2012-12-31 14:05 ` James Harkins
2012-12-31 14:19 ` Bastien
2013-01-01 2:13 ` James Harkins [this message]
2013-01-01 16:10 ` Bastien
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://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAFniQ7Uz_GYF13r9eE=AYQCpdVc027FZygUAmVrL-JMKNB9LFg@mail.gmail.com' \
--to=jamshark70@gmail.com \
--cc=Emacs-orgmode@gnu.org \
--cc=jamshark70@dewdrop-world.net \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).