how do I get started using Emacs' documentation?

Question

I want to familiarize myself with Emacs' self-documenting help systems so I can figure things out on my own.

Example: I want to learn how to use org-mode's :VISIBILITY: property so that I can make certain subtrees always open in an expanded state.

I took a guess as to the syntax...

:VISIBILITY: CHILDREN

...but it didn't work.

So I want to use the help system to figure it out.

So I do this:

M-x apropos

Apropos symbol (word list or regexp): org visibility

No help there.

C-h v Describe variable org visibility org-inhibit-startup-visibility-stuff

No help there.

C-h a visibility

org-set-visibility-according-to-property is an interactive Lisp function in `org.el'.

(org-set-visibility-according-to-property &optional NO-CLEANUP)

Switch subtree visibilities according to :VISIBILITY: property.

C-h a visibility

org-toggle-custom-properties-visibility is an interactive Lisp function in `org.el'.

(org-toggle-custom-properties-visibility)

...and I still am no closer to knowing how to use org-mode's :VISIBILITY: property.

How can I use the help system better to find what I'm looking for?

Answer 1

The info manuals are the most detailed documentation, and they're all indexed.

As a convenience, the (emacs) and (elisp) manuals both have commands for searching their index from anywhere (emacs-index-search and elisp-index-search), but there are many libraries which have their own top-level manual, and unsurprisingly org-mode is one of them. You'll see it listed in the main page when you type C-hi (followed by d if you were already reading some other info page), or you can jump directly to it with:

C-hig (org) RET

You may need to learn how to use the info reader first. From the *info* buffer you can type h to start its tutorial, and d to return to the top level page (which has some useful notes at the top).

Once you're in any specific manual, you can search the index with I (upper-case letter i). Note that lower-case i also searches, but I find the former more useful in general.

so in this case I would first try I :VISIBILITY: RET

That gives no results (and I note that it's actually ignoring the leading : for some reason I'm unsure about right now), but trying again with VISIBILITY (without the colons) gives a bunch of results which you can follow (primarily in the (org) Visibility cycling node, in which I can see the list of values you're looking for).

You can also isearch through the text of a manual in the normal way with C-s. That will search in the current node but, upon failure, typing C-s again will take you to the next matching node it finds in that manual. This is incredibly useful if the thing you're looking for isn't indexed.

Note that if you don't know which manual to search, you can search all info manuals using info-apropos (which is naturally much slower).

There's also http://emacswiki.org/emacs/SelfDocumentation (which doesn't go into much detail, but you should at least ensure you're familiar with the things it does mention).