From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jorge Subject: Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)] Date: Thu, 29 Sep 2016 15:36:27 -0300 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:38324) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bpgC8-0006un-4f for emacs-orgmode@gnu.org; Thu, 29 Sep 2016 14:36:34 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bpgC5-0005L4-7b for emacs-orgmode@gnu.org; Thu, 29 Sep 2016 14:36:31 -0400 Received: from mail-qk0-x235.google.com ([2607:f8b0:400d:c09::235]:33498) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bpgC5-0005Kp-3C for emacs-orgmode@gnu.org; Thu, 29 Sep 2016 14:36:29 -0400 Received: by mail-qk0-x235.google.com with SMTP id n189so12794015qke.0 for ; Thu, 29 Sep 2016 11:36:28 -0700 (PDT) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: org mode To confirm those bugs that needed confirming by testing, I started Emacs wi= th 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. =E2=80=A2 org-id-update-id-locations docstring The only real formal parameters are `files' and `silent', but the docstri= ng mentions parameter `check'. =E2=80=A2 `org-insert-heading' docstring =E2=80=A2 In the 4th paragraph: With one universal prefix argument, set the user option =E2=80=98org-insert-heading-respect-content=E2=80=99 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 anywh= ere/ within normal lines, except at column 0; in the latter case, it creates= the new heading /before/ the original heading. =E2=80=A2 When describing the behavior with C-u C-u, it wrongly substitut= es "grandparent" for "parent". =E2=80=A2 Finally, the following two paragraphs near the end of the docst= ring 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 =E2=80=98org-M-RET-may-split-line= =E2=80=99 on how to modify this behavior). If point is at the beginning of a normal line, turn this line into a heading. =E2=80=A2 [info:org#Structure editing] I looked at the code, and C- (org-insert-heading-respect-content) ju= st calls (org-insert-heading '(4) invisible-ok), so it has the same effect a= s C-u M-. The manual could mention that C- has the same effect a= s C-u M-, to aid the user's learning process, as she would just need t= o 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-. And the description of C- is actually wrong: Just like `M-', 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- may create a new plain list item, wh= ile C- always creates a new heading, and that C- never splits the heading. Please rewrite the whole description. =E2=80=A2 org-insert-todo-heading docstring omits the behavior of inserting a new item with an unchecked checkbox whe= n invoked at a plain list. =E2=80=A2 [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. Actual= ly it defaults to nil. =E2=80=A2 [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. =E2=80=A2 [info:org#Checkboxes] =E2=80=A2 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. =E2=98=90 2. =E2=98=91 One invocation will actually turn it into 1. =E2=98=91 2. =E2=98=91 =E2=80=A2 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 q= uick testing, this only happens if the invocation happens at column 0. =E2=80=A2 [info:org#Agenda commands] Misreports the effect of C-u on (see the docstring). =E2=80=A2 [info:org#Countdown timer] "prefix numeric argument" =E2=86=92 "numeric prefix argument" =E2=80=A2 [info:org#Conventions] says "Easy templates insert lowercase keywords". Actually, according to = my quick test they insert all-capitals keywords. =E2=80=A2 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"). =E2=80=A2 [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-le= vel. Ditto for C-c C-b. =E2=80=A2 Inconsistency about the main keybinding for org-occur C-c / help window mentions only "r" for regexp, not "/". [info:org#Spars= e trees] also mentions only "r" =E2=80=93 not "/". So they treat C-c / r a= s the main keybinding for org-occur. The docstring of org-sparse-tree, however, mentions both, and "r" /more/ prominently than "/". =E2=80=A2 [info:org#Footnotes] about `C-c '': The keybinding `C-c '' is wri= tten twice. Besides, in the description, the sentence This may be useful if editing footnotes in a narrowed buffer. seems incomplete. =E2=80=A2 org-copy-special docstring wrongly substitutes org-table-copy for org-table-copy-region. =E2=80=A2 [info:org#Filtering/limiting agenda items] Omits the fact that org-agenda-filter-by-tag-refine is obsolete. Also sa= ys: 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. =E2=80=A2 org-update-statistics-cookies docstring should explicitly document that C-u makes it update all cookies in the buffer. =E2=80=A2 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). =E2=80=A2 Typos listed in the format "\"$wrong>\" =E2=86=92 \"$correct\"" =E2=80=A2 [info:org#The date/time prompt] "ISO week for" =E2=86=92 "ISO week four". =E2=80=A2 [info:org#Column width and alignment] "string-rich column" =E2=86=92 "string-rich columns" =E2=80=A2 [info:org#Column groups] `>' to indicate the end of a column "column" =E2=86=92 "group" =E2=80=A2 [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. =E2=80=A2 [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 actu= ally /prepended/ (not /appended/) to the tag. I suggest replacing everythin= g after the comma with: "the tag will simply be appended in order to crea= te the link." =E2=80=A2 [info:org#Tag inheritance] "with those tags" =E2=86=92 "with all those tags" =E2=80=A2 [info:org#Tag hierarchy] all members in the group and its subgroup "subgroup" =E2=86=92 "subgroups" =E2=80=A2 [info:org#Tag searches] "to find entries which are tagged, like `Kathy' or `Sally'" =E2=86=92 "to find entries tagged as `Kathy' or `Sally'" =E2=80=A2 "org-metaright" docstring "org-indnet-drawer" =E2=86=92 "org-indent-drawer" =E2=80=A2 org-yank docstring: "but only if doing so would now" =E2=86=92 "except if doing so would" (= or at least fix "now" =E2=86=92 "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/) --=20 =E2=80=A2 I am Brazilian. I hope my English is correct and I welcome corre= ctions. =E2=80=A2 Please adopt free formats like PDF, ODF, Org, LaTeX, Opus, WebM a= nd 7z. =E2=80=A2 Free (as in free speech) software for Android: https://f-droid.or= g/