From mboxrd@z Thu Jan 1 00:00:00 1970 From: Robert Horn Subject: Re: Confused about the explanation for 'org-cycle' Date: Thu, 28 Sep 2017 11:29:48 -0400 Message-ID: References: <22975.53875.671661.416361@frac.u-strasbg.fr> <874lrzl1gr.fsf@fastmail.fm> <87lgl963jf.fsf@nicolasgoaziou.fr> <22986.5564.583945.909910@frac.u-strasbg.fr> <877ewl4u8s.fsf@nicolasgoaziou.fr> <22986.19586.309718.302611@frac.u-strasbg.fr> <87h8vmopww.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:35134) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dxalA-0006b0-0N for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 11:29:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dxal7-0004mi-B8 for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 11:29:56 -0400 Received: from mailbackend.panix.com ([166.84.1.89]:37656) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dxal7-0004mK-6c for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 11:29:53 -0400 In-reply-to: <87h8vmopww.fsf@nicolasgoaziou.fr> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Nicolas Goaziou Cc: emacs-orgmode@gnu.org, Alain.Cochard@unistra.fr Nicolas Goaziou writes: > Completeness is not possible. For example, we do not document every > variable in the manual. Besides, when reading a pile of special rules > for special cases, the reader may lose focus and miss the whole concept. > > BTW, a "docstring" is the documentation you get when using, e.g., `C-h > v' or `C-h f'. > Actually, an effective way to deal with this is to have two sections: "All external org functions" and "All external org variables" that merely lists them all alphabetically, and begins with a short paragraph on what a doc-string is and how to get it for these. This might also be a place to put a short paragraph about how internal org functions and variables are identified, and why it is a good idea to avoid using them in added features. E.g., the fact that they may be replaced, removed, or revised drastically by subsequent org releases. It's not quite as simple as doing a search for defun, pruning, and sorting, but it shouldn't be much more than that. This would probably help new users a lot. R Horn