From mboxrd@z Thu Jan  1 00:00:00 1970
From: Bastien <bzg@altern.org>
Subject: Re: Visibility cycling of plain lists?
Date: Tue, 01 Jan 2013 17:10:55 +0100
Message-ID: <87pq1o3muo.fsf@bzg.ath.cx>
References: <CAFniQ7Xmm6fWHo2t3wQC4EaC13D5C2tFA7dwtbA+U1Tn+Q1ExQ@mail.gmail.com>
	<CAFniQ7U3HR_v-cxSL8f6MGVBg5vS-xsF7ZmOysnvgO6WSgS=Tw@mail.gmail.com>
	<87k3ryo95z.fsf@bzg.ath.cx>
	<CAFniQ7XtaBQNUsSvKBy-zgiCaFisrE_p-Z_c0THg5Nut71F-Ow@mail.gmail.com>
	<87sj6ml2x5.fsf@bzg.ath.cx>
	<CAFniQ7Uz_GYF13r9eE=AYQCpdVc027FZygUAmVrL-JMKNB9LFg@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain
Return-path: <emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([208.118.235.92]:55597)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <bastienguerry@gmail.com>) id 1Tq4Qg-0003VP-2X
	for Emacs-orgmode@gnu.org; Tue, 01 Jan 2013 11:11:02 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <bastienguerry@gmail.com>) id 1Tq4Qb-0007LR-Io
	for Emacs-orgmode@gnu.org; Tue, 01 Jan 2013 11:11:01 -0500
Received: from mail-wi0-f176.google.com ([209.85.212.176]:45800)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <bastienguerry@gmail.com>) id 1Tq4Qb-0007LD-CA
	for Emacs-orgmode@gnu.org; Tue, 01 Jan 2013 11:10:57 -0500
Received: by mail-wi0-f176.google.com with SMTP id hm6so9847772wib.15
	for <Emacs-orgmode@gnu.org>; Tue, 01 Jan 2013 08:10:56 -0800 (PST)
In-Reply-To: <CAFniQ7Uz_GYF13r9eE=AYQCpdVc027FZygUAmVrL-JMKNB9LFg@mail.gmail.com>
	(James Harkins's message of "Tue, 1 Jan 2013 10:13:05 +0800")
List-Id: "General discussions about Org-mode." <emacs-orgmode.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/emacs-orgmode>
List-Post: <mailto:emacs-orgmode@gnu.org>
List-Help: <mailto:emacs-orgmode-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=subscribe>
Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
To: jamshark70@dewdrop-world.net
Cc: Emacs-orgmode@gnu.org

Hi James,

James Harkins <jamshark70@gmail.com> writes:

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

If find the above a bit clumsy and repetitive, I just updated the
docstring like this:

  When this is the symbol `integrate', then integrate plain list
  items when cycling, as if they were children of outline headings.

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

I agree -- but what's difficult is that documentation problems are
often mixed problems, about content *and* UI.  And content can not 
always alleviate the guesswork induced by unfamiliar UI.

-- 
 Bastien