* Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)]
@ 2016-09-29 18:36 Jorge
2016-09-29 20:36 ` Nicolas Goaziou
0 siblings, 1 reply; 6+ messages in thread
From: Jorge @ 2016-09-29 18:36 UTC (permalink / raw)
To: org mode
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/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)]
2016-09-29 18:36 Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)] Jorge
@ 2016-09-29 20:36 ` Nicolas Goaziou
2016-09-30 13:36 ` Jorge
0 siblings, 1 reply; 6+ messages in thread
From: Nicolas Goaziou @ 2016-09-29 20:36 UTC (permalink / raw)
To: Jorge; +Cc: org mode
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)]
2016-09-29 20:36 ` Nicolas Goaziou
@ 2016-09-30 13:36 ` Jorge
2016-10-01 22:36 ` Nicolas Goaziou
0 siblings, 1 reply; 6+ messages in thread
From: Jorge @ 2016-09-30 13:36 UTC (permalink / raw)
To: org mode
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/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)]
2016-09-30 13:36 ` Jorge
@ 2016-10-01 22:36 ` Nicolas Goaziou
2016-10-02 19:40 ` Jorge
0 siblings, 1 reply; 6+ messages in thread
From: Nicolas Goaziou @ 2016-10-01 22:36 UTC (permalink / raw)
To: Jorge; +Cc: org mode
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)]
2016-10-01 22:36 ` Nicolas Goaziou
@ 2016-10-02 19:40 ` Jorge
2016-10-04 10:03 ` Nicolas Goaziou
0 siblings, 1 reply; 6+ messages in thread
From: Jorge @ 2016-10-02 19:40 UTC (permalink / raw)
To: org mode
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/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)]
2016-10-02 19:40 ` Jorge
@ 2016-10-04 10:03 ` Nicolas Goaziou
0 siblings, 0 replies; 6+ messages in thread
From: Nicolas Goaziou @ 2016-10-04 10:03 UTC (permalink / raw)
To: Jorge; +Cc: org mode
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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-10-04 10:03 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-09-29 18:36 Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)] Jorge
2016-09-29 20:36 ` Nicolas Goaziou
2016-09-30 13:36 ` Jorge
2016-10-01 22:36 ` Nicolas Goaziou
2016-10-02 19:40 ` Jorge
2016-10-04 10:03 ` Nicolas Goaziou
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).