To confirm those bugs that needed confirming by testing, I started Emacs with
an empty init file. I also used this Emacs instance to compose this email.
This is the first batch of documentation problems. I will report the rest
later, because preparing this first batch already took several hours.
• org-id-update-id-locations docstring
The only real formal parameters are `files' and `silent', but the docstring
mentions parameter `check'.
• `org-insert-heading' docstring
• In the 4th paragraph:
With one universal prefix argument, set the user option
‘org-insert-heading-respect-content’ to t for the duration of
the command. This modifies the behavior described above in
this ways: on list items and at the /beginning/ of normal
lines, force the insertion of a heading after the current
subtree.
According to my quick test, this behavior actually occurs /almost anywhere/
within normal lines, except at column 0; in the latter case, it creates the
new heading /before/ the original heading.
• When describing the behavior with C-u C-u, it wrongly substitutes
"grandparent" for "parent".
• Finally, the following two paragraphs near the end of the docstring seem
redundant (see the 2nd and 3rd paragraphs):
If point is at the beginning of a headline, insert a sibling
before the current headline. If point is not at the beginning,
split the line and create a new headline with the text in the
current line after point (see ‘org-M-RET-may-split-line’ on how
to modify this behavior).
If point is at the beginning of a normal line, turn this line
into a heading.
• [info:org#Structure editing]
I looked at the code, and C-<RET> (org-insert-heading-respect-content) just
calls (org-insert-heading '(4) invisible-ok), so it has the same effect as
C-u M-<RET>. The manual could mention that C-<RET> has the same effect as
C-u M-<RET>, to aid the user's learning process, as she would just need to
memorize this quick fact, instead of understanding both behaviors and
deducing they're equal). Also the manual doesn't adequately explain the
effect of C-u M-<RET>. And the description of C-<RET> is actually wrong:
Just like `M-<RET>', except when adding a new heading below the
current heading, the new heading is placed after the body instead
of before it. This command works from anywhere in the entry.
/After the body/? Doesn't it mean /after the entry/? Besides, there are
additional differences: that M-<RET> may create a new plain list item, while
C-<RET> always creates a new heading, and that C-<RET> never splits the
heading. Please rewrite the whole description.
• org-insert-todo-heading docstring
omits the behavior of inserting a new item with an unchecked checkbox when
invoked at a plain list.
• [info:org#Initial visibility]
The startup visibility options are ignored when the file is open
for the first time during the agenda generation: if you want the
agenda to honor the startup visibility, set
`org-agenda-inhibit-startup' to `nil'.
This implies that org-agenda-inhibit-startup defaults to non-nil. Actually
it defaults to nil.
• [info:org#Plain lists], paragraph about "C-c -"
If there is an active region when calling this, selected text
will be changed into an item. With a prefix argument, all lines
will be converted to list items. If the first line already was a
list item, any item marker will be removed from the list.
The manual switched the effect of the prefix argument. Actually if there is
an active region and no prefix argument, it converts all lines into list
items, and with an active region and a prefix argument, it converts the
entire region into one item.
• [info:org#Checkboxes]
• The manual says that if "C-c C-x C-b" is invoked in a headline, Org toggles
checkboxes in the region between this headline and the next. Actually it
does not. For example, if the list started like this:
1. ☐
2. ☑
One invocation will actually turn it into
1. ☑
2. ☑
• A footnote says that "C-u C-c C-c" is invoked on the first item of a list
with no checkbox, Org adds checkboxes to the rest of the list. In my quick
testing, this only happens if the invocation happens at column 0.
• [info:org#Agenda commands]
Misreports the effect of C-u on <SPC> (see the docstring).
• [info:org#Countdown timer]
"prefix numeric argument" → "numeric prefix argument"
• [info:org#Conventions]
says "Easy templates insert lowercase keywords". Actually, according to my
quick test they insert all-capitals keywords.
• Mentions of obsolete aliases
I don't know if this is intentional for compatibility with earlier Emacs
releases or an error, but I thought I should report just in case:
1. [info:org#Global and local cycling]:
1. "show-branches" ("outline-show-branches").
2. "show-all" ("outline-show-all").
3. "show-children" ("outline-show-children").
2. "org-kill-note-or-show-branches" docstring mentions "show-branches"
("outline-show-branches").
3. "org-agenda-show-and-scroll-up" docstring mentions "show-subtree"
("outline-show-subtree").
• [info:org#Motion]
1. C-c C-n invokes org-next-visible-heading, not
outline-next-visible-heading. Ditto for C-c C-p.
2. C-c C-f invoke org-forward-heading-same-level, not org-forward-same-level.
Ditto for C-c C-b.
• Inconsistency about the main keybinding for org-occur
C-c / help window mentions only "r" for regexp, not "/". [info:org#Sparse
trees] also mentions only "r" – not "/". So they treat C-c / r as the main
keybinding for org-occur. The docstring of org-sparse-tree, however,
mentions both, and "r" /more/ prominently than "/".
• [info:org#Footnotes] about `C-c '': The keybinding `C-c '' is written twice.
Besides, in the description, the sentence
This may be useful if editing footnotes in a narrowed buffer.
seems incomplete.
• org-copy-special docstring
wrongly substitutes org-table-copy for org-table-copy-region.
• [info:org#Filtering/limiting agenda items]
Omits the fact that org-agenda-filter-by-tag-refine is obsolete. Also says:
If the first key you press is either `+' or `-', the previous
filter will be narrowed by requiring or forbidding the selected
additional tag.
but, according to my test, '+' is superfluous, because just by hitting `/'
and selecting the tag, the filter is refined to require the tag.
• org-update-statistics-cookies docstring
should explicitly document that C-u makes it update all cookies in the
buffer.
• Docstring of org-id-link-to-org-use-id
wrongly substitutes C-c C-l for C-c l. And after making this correction,
perhaps you should mention that C-c l is a custom keybinding (only a
suggestion).
• Typos listed in the format "\"$wrong>\" → \"$correct\""
• [info:org#The date/time prompt]
"ISO week for" → "ISO week four".
• [info:org#Column width and alignment]
"string-rich column" → "string-rich columns"
• [info:org#Column groups]
`>' to indicate the end of a column
"column" → "group"
• [info:org#External links]
`file:projects.org::*task title heading search in Org'
`file(2)'
The description (starting with "title" and ending in the next line with
"file(2)") is misaligned.
• [info:org#Link abbreviations]
If the replacement text doesn't contain any specifier, it will
simply be appended to the string in order to create the link.
The "it" refers to "replacement text", but the replacement text is actually
/prepended/ (not /appended/) to the tag. I suggest replacing everything
after the comma with: "the tag will simply be appended in order to create
the link."
• [info:org#Tag inheritance]
"with those tags" → "with all those tags"
• [info:org#Tag hierarchy]
all members in the group and its subgroup
"subgroup" → "subgroups"
• [info:org#Tag searches]
"to find entries which are tagged, like `Kathy' or `Sally'" →
"to find entries tagged as `Kathy' or `Sally'"
• "org-metaright" docstring
"org-indnet-drawer" → "org-indent-drawer"
• org-yank docstring:
"but only if doing so would now" → "except if doing so would" (or at least
fix "now" → "not")
Thank you and regards.
Emacs : GNU Emacs 25.1.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.18.9)
of 2016-09-18
Package: Org-mode version 8.3.6 (8.3.6-4-g4835be-elpaplus @
/home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)
--
• I am Brazilian. I hope my English is correct and I welcome corrections.
• Please adopt free formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z.
• Free (as in free speech) software for Android: https://f-droid.org/
