From: Robert Horn <rjhorn@alum.mit.edu>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: emacs-orgmode@gnu.org, Alain.Cochard@unistra.fr
Subject: Re: Confused about the explanation for 'org-cycle'
Date: Thu, 28 Sep 2017 11:29:48 -0400 [thread overview]
Message-ID: <m3d16adeoj.fsf@alum.mit.edu> (raw)
In-Reply-To: <87h8vmopww.fsf@nicolasgoaziou.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
next prev parent reply other threads:[~2017-09-28 15:29 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-09-18 14:04 Confused about the explanation for 'org-cycle' Alain.Cochard
2017-09-19 5:08 ` Matt Lundin
2017-09-20 10:57 ` Nicolas Goaziou
2017-09-26 8:54 ` Alain.Cochard
2017-09-26 10:41 ` Nicolas Goaziou
2017-09-26 12:48 ` Alain.Cochard
2017-09-28 13:44 ` org-list-empty-line-terminates-plain-lists removed but still mentioned in the manual Alain.Cochard
2017-09-28 14:07 ` Nicolas Goaziou
2017-09-28 14:31 ` Confused about the explanation for 'org-cycle' Nicolas Goaziou
2017-09-28 15:29 ` Robert Horn [this message]
2017-09-28 16:10 ` Kyle Meyer
2017-09-28 16:17 ` Eric S Fraga
2017-09-28 21:04 ` Alain.Cochard
2017-09-28 21:22 ` Josiah Schwab
2017-09-28 21:30 ` Nicolas Goaziou
2017-10-05 8:17 ` Alain.Cochard
2017-11-10 17:23 ` How to use case sensitive org-search-view? Alain.Cochard
2017-11-14 14:26 ` Matt Lundin
2017-11-14 15:30 ` Alain.Cochard
2017-11-14 20:35 ` Nicolas Goaziou
2017-11-14 20:55 ` Tim Cross
2017-11-15 14:02 ` Nicolas Goaziou
2017-11-15 21:14 ` Tim Cross
2017-11-16 10:05 ` Alain.Cochard
2017-11-15 10:49 ` Alain.Cochard
2017-11-15 11:55 ` Nicolas Goaziou
2017-11-15 12:35 ` Alain.Cochard
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=m3d16adeoj.fsf@alum.mit.edu \
--to=rjhorn@alum.mit.edu \
--cc=Alain.Cochard@unistra.fr \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
/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).