[O] Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)]

[Jorge]

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/