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

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/

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

[Nicolas Goaziou]

Hello,

Jorge <jorge13515@gmail.com> writes:

> This is the first batch of documentation problems.  I will report the rest
> later, because preparing this first batch already took several hours.

Those are fixed, except the points below.

>   • When describing the behavior with C-u C-u, it wrongly substitutes
>     "grandparent" for "parent".

I think "grandparent" is correct. In the following document

  * H1
  ** H2
  Text<--point

"H2" is the parent headline of "Text" and as a consequence, "H1" is its
grandparent.

> • [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.

You are right, M-RET and C-RET are confusing, and making C-u M-RET
a duplicate of C-RET is wasting some important keybinding. This was
discussed on this ML already (with Rasmus) but led nowhere so far.

In any case, it is more future-proof to not insist on the fact that
C-RET is C-u M-RET.

Thank you for this tedious, yet very important work.

Regards,

-- 
Nicolas Goaziou

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

[Jorge]

On 29 September 2016 at 17:36, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> I think "grandparent" is correct. In the following document
>
>   * H1
>   ** H2
>   Text<--point
>
> "H2" is the parent headline of "Text" and as a consequence, "H1" is its
> grandparent.
What if point is in the headline, which is often the case?  Besides the
docstring is inconsistent:
      With two universal prefix arguments, insert the heading at the end
      of the grandparent subtree.  For example, if point is within a
      2nd-level heading, then it will insert a 2nd-level heading at the
      end of the 1st-level parent heading.

In the first sentence it says "grandparent subtree", whereas in the second
sentence it says "parent heading".  And the manual says "parent":
      Calling this command with `C-u C-u' will unconditionally respect
      the headline's content and create a new item at the end of the
      parent subtree.

Perhaps uniformity of terminology would help here.

> You are right, M-RET and C-RET are confusing, and making C-u M-RET
> a duplicate of C-RET is wasting some important keybinding. This was
> discussed on this ML already (with Rasmus) but led nowhere so far.
>
> In any case, it is more future-proof to not insist on the fact that
> C-RET is C-u M-RET.
I think that, whether we describe both behaviors separately or tell
the user that
C-RET is equivalent to C-u M-RET, the commitment (to not change the behavior)
is the same.  But if you still think that describing both separately is more
future-proof, I won't argue.

But I still ask you to look at the other points I made about that manual
section: that it doesn't adequately explain the effect of C-u M-RET, and that
the description of C-RET is actually wrong.

> Thank you for this tedious, yet very important work.
Thank you very much for working on Org!

-- 
• 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/

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

[Nicolas Goaziou]

Hello,

Jorge <jorge13515@gmail.com> writes:

> On 29 September 2016 at 17:36, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>> I think "grandparent" is correct. In the following document
>>
>>   * H1
>>   ** H2
>>   Text<--point
>>
>> "H2" is the parent headline of "Text" and as a consequence, "H1" is its
>> grandparent.
> What if point is in the headline, which is often the case?  Besides the
> docstring is inconsistent:
>       With two universal prefix arguments, insert the heading at the end
>       of the grandparent subtree.  For example, if point is within a
>       2nd-level heading, then it will insert a 2nd-level heading at the
>       end of the 1st-level parent heading.
>
> In the first sentence it says "grandparent subtree", whereas in the second
> sentence it says "parent heading".  And the manual says "parent":
>       Calling this command with `C-u C-u' will unconditionally respect
>       the headline's content and create a new item at the end of the
>       parent subtree.

In this case, both "parent" and "grandparent" are confusing terms.
I made a change to M-RET docstring, hopefully eschewing the confusion.
Please let me know if there is still something wrong there.

> But I still ask you to look at the other points I made about that manual
> section: that it doesn't adequately explain the effect of C-u M-RET, and that
> the description of C-RET is actually wrong.

I overlooked that part. Fixed. Thank you.

Regards,

-- 
Nicolas Goaziou

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

[Jorge]

On 1 October 2016 at 19:36, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> In this case, both "parent" and "grandparent" are confusing terms.
> I made a change to M-RET docstring, hopefully eschewing the confusion.
> Please let me know if there is still something wrong there.
It is good now, but I still have some questions and observations:

First, there is some undocumented behavior if M-RET is called in the headline
after column 0 but before the headline text (e.g. if point is on the priority
cookie).  It then splits the heading just before the PROPERTIES drawer.  But I
don’t know if this is worthy of documentation.

Now something which I do consider worthy of description:
      This forces the insertion of a heading after the current subtree,
      independently on the location of point.
At least in Org version 8.3.6 (8.3.6-4-g4835be-elpaplus @
/home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/), the new subtree is
positioned /before/ the current one if M-RET (even C-u M-RET) is invoked at
column 0 in the headline.  You could change the text to
      This forces the insertion of a heading after the current subtree,
      for any position of point except at column 0 in the headline.
Or you could change the code to remove this non-uniform behavior at column 0 of
the headline.

Now a very small detail:
      With double \\[universal-argument] \\[universal-argument] prefix
A “double \\[universal-argument] \\[universal-argument]” could be interpreted
as C-u C-u C-u C-u.  I think it would be better to say just
      With a \\[universal-argument] \\[universal-argument] prefix

-- 
• 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/

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

[Nicolas Goaziou]

Hello,

Jorge <jorge13515@gmail.com> writes:

> First, there is some undocumented behavior if M-RET is called in the headline
> after column 0 but before the headline text (e.g. if point is on the priority
> cookie).  It then splits the heading just before the PROPERTIES drawer.  But I
> don’t know if this is worthy of documentation.

More documentation cannot hurt. I modified the docstring.

> Now something which I do consider worthy of description:
>       This forces the insertion of a heading after the current subtree,
>       independently on the location of point.
> At least in Org version 8.3.6 (8.3.6-4-g4835be-elpaplus @
> /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/), the new subtree is
> positioned /before/ the current one if M-RET (even C-u M-RET) is invoked at
> column 0 in the headline.  You could change the text to
>       This forces the insertion of a heading after the current subtree,
>       for any position of point except at column 0 in the headline.
> Or you could change the code to remove this non-uniform behavior at column 0 of
> the headline.

I did the latter.

> Now a very small detail:
>       With double \\[universal-argument] \\[universal-argument] prefix
> A “double \\[universal-argument] \\[universal-argument]” could be interpreted
> as C-u C-u C-u C-u.  I think it would be better to say just
>       With a \\[universal-argument] \\[universal-argument] prefix

Fixed.

Thank you.

Regards,

-- 
Nicolas Goaziou