Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Jorge P. de Morais Neto]

* Small documentation errors

Hi.  Below I report a series of small documentation errors.  Please tell
me whether it was helpful to coalesce these several errors into one bug
report or I should have filed several reports.

** [[info:org#Sparse Trees]]

 The final paragraph recommends the command ‘C-c C-e v’ to export only
the visible part of the document.  The correct keybinding, however, is
‘C-c C-e C-v’.

** [[info:org#Plain Lists]]

The description of `C-c -' inverts the effect of the prefix argument.

** [[info:org#Drawers]]

I don't understand the sentence

       Completion over drawer keywords is also possible using ‘M-<TAB>’

Could give me a simple example of drawer keyword completion?

** [[info:org#TODO Basics]]

This section omits `C-S-<RET>'.  Is that intentional?

** [info:org#Tracking TODO state changes]

The following sentence is misplaced, interrupting the previous train of
thought:

    To record a timestamp without a note for TODO keywords configured
    with `@', just type `C-c C-c' to enter a blank note when prompted.

** Docstring of `org-time-stamp-inactive'

It has less information than the docstring of `org-time-stamp'.  If that
is intentional, then I suggest at least referring to the docstring of
`org-time-stamp' for more information.

Also, it says that inactive timestamp do not link to the calendar and
cannot be changed with the S-cursor keys; the actual behavior -- which I
tested both in an updated Spacemacs (develop branch) and in `emacs -q`
-- contradicts both assertions.

Finally, the last paragraph says:

    When called with two universal prefix arguments, insert an active
    time stamp with the current time without prompting the user.

Clearly it should say /inactive/ instead of /active/.

* Feedback

I am obsessed with detail and I welcome feedback about that.  Please
tell me whether I am nitpicking.

Regards

Emacs  : GNU Emacs 27.0.90 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.5)
 of 2020-04-11
Package: Org mode version 9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)
-- 
- <https://jorgemorais.gitlab.io/justice-for-rms/>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- Please adopt free/libre formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z.
- Free/libre software for Replicant, LineageOS and Android: https://f-droid.org
- [[https://www.gnu.org/philosophy/free-sw.html][What is free software?]]

Re: Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Kyle Meyer]

"Jorge P. de Morais Neto" <jorge@disroot.org> writes:

> * Small documentation errors
>
> Hi.  Below I report a series of small documentation errors.  Please tell
> me whether it was helpful to coalesce these several errors into one bug
> report or I should have filed several reports.

Thanks for sending this.  My personal preference would be more focused
reports.  (And of course patches would be even better.)

I'm responding to some of the points below, focusing on what I viewed as
the more clear-cut errors.

> ** [[info:org#Sparse Trees]]
>
>  The final paragraph recommends the command ‘C-c C-e v’ to export only
> the visible part of the document.  The correct keybinding, however, is
> ‘C-c C-e C-v’.

Corrected.

> ** [[info:org#Plain Lists]]
>
> The description of `C-c -' inverts the effect of the prefix argument.

I'm not seeing that behavior on my end.  With

  a
  b

and a region spanning before "a" and after "b", hitting 'C-c -' gives me

  - a
  - b

Hitting 'C-u C-c -' instead I get

  - a
    b

AFAICS that matches the manual's description.

> ** Docstring of `org-time-stamp-inactive'
[...]
> Also, it says that inactive timestamp do not link to the calendar and
> cannot be changed with the S-cursor keys; the actual behavior -- which I
> tested both in an updated Spacemacs (develop branch) and in `emacs -q`
> -- contradicts both assertions.

That statement has been around a while.  Perhaps that used to be a case,
but, testing a few recent versions, it certainly doesn't seem true now.
I've removed that part.

> Finally, the last paragraph says:
>
>     When called with two universal prefix arguments, insert an active
>     time stamp with the current time without prompting the user.
>
> Clearly it should say /inactive/ instead of /active/.

This was recently fixed by Leo Vivier in acd163596 (2020-04-08).

Re: Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Jorge P. de Morais Neto]

Em [2020-04-12 dom 22:35:09+0000], Kyle Meyer escreveu:

> Thanks for sending this.  My personal preference would be more focused
> reports.  (And of course patches would be even better.)

Regarding patches, I feel I am too inexperienced at this moment to
efficiently write good patches.  It is possible, though, that I am just
unduly insecure.  Perfectionism and low self esteem combine to generate
a lot of insecurity.

> "Jorge P. de Morais Neto" <jorge@disroot.org> writes:
>> ** [[info:org#Plain Lists]]
>>
>> The description of `C-c -' inverts the effect of the prefix argument.
>
> I'm not seeing that behavior on my end.  With
>
>   a
>   b
>
> and a region spanning before "a" and after "b", hitting 'C-c -' gives me
>
>   - a
>   - b
>
> Hitting 'C-u C-c -' instead I get
>
>   - a
>     b

Yes, this is the behavior I get too.  But see what the manual says:

    If there is an active region when calling this, selected text is
    changed into *an item*.
[ my emphasis ]

It says `C-c -' changes the (potentially multiple) lines into *an item*
(singular).  With the prefix argument it says:

    With a prefix argument, all lines are converted to *list items*.
[ my emphasis ]

It says `C-c -' changes the (potentially multiple) lines into *list
items* (plural).

Regards
-- 
- <https://jorgemorais.gitlab.io/justice-for-rms/>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- <https://www.defectivebydesign.org/>
- <https://www.gnu.org/>

Re: Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Kyle Meyer]

Jorge P. de Morais Neto <jorge+list@disroot.org> writes:

> Em [2020-04-12 dom 22:35:09+0000], Kyle Meyer escreveu:
>
>> Thanks for sending this.  My personal preference would be more focused
>> reports.  (And of course patches would be even better.)
>
> Regarding patches, I feel I am too inexperienced at this moment to
> efficiently write good patches.  It is possible, though, that I am just
> unduly insecure.  Perfectionism and low self esteem combine to generate
> a lot of insecurity.

Well, no pressure to send patches if you're not comfortable doing so.
But sending a patch with an error or that needs work is not an issue.
I'd say the mostly likely outcome is that someone will politely point
that out.

Not so different really than saying something wrong like:

Kyle Meyer <kyle@kyleam.com> writes:

>> The description of `C-c -' inverts the effect of the prefix argument.
> [...]
> AFAICS that matches the manual's description.

And someone patiently explaining that "as far as Kyle can see"
apparently wasn't very far:

Jorge P. de Morais Neto <jorge+list@disroot.org> writes:

> Yes, this is the behavior I get too.  But see what the manual says:
>
>     If there is an active region when calling this, selected text is
>     changed into *an item*.
> [ my emphasis ]
>
> It says `C-c -' changes the (potentially multiple) lines into *an item*
> (singular).  With the prefix argument it says:
>
>     With a prefix argument, all lines are converted to *list items*.
> [ my emphasis ]
>
> It says `C-c -' changes the (potentially multiple) lines into *list
> items* (plural).

Thanks.  I'll fix that (my) tonight.

Re: Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Jorge P. de Morais Neto]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: 0001-doc-org-manual.org-Tracking-TODO-state-changes-move-.patch --]
[-- Type: text/x-diff, Size: 1524 bytes --]

From 474192b67077b3a7bfaa8e9ff152b1a9ac7524f3 Mon Sep 17 00:00:00 2001
From: "Jorge P. de Morais Neto" <jorge+git@disroot.org>
Date: Wed, 11 Aug 2021 17:13:06 -0300
Subject: [PATCH] * doc/org-manual.org (Tracking TODO state changes): move
 sentence

The sentence was misplaced, interrupting the train of thought.  I also
did not understand the need for disabling paragraph indentation, so I
removed the directive.
---
 doc/org-manual.org | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 977ef80b9..d34d33561 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -4205,10 +4205,6 @@ example, with the setting
       '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)")))
 #+end_src
 
-#+texinfo: @noindent
-To record a timestamp without a note for TODO keywords configured with
-=@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted.
-
 #+vindex: org-log-done
 You not only define global TODO keywords and fast access keys, but
 also request that a time is recorded when the entry is set to =DONE=,
@@ -4228,6 +4224,9 @@ to a buffer:
 
 : #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@)
 
+To record a timestamp without a note for TODO keywords configured with
+=@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted.
+
 #+cindex: @samp{LOGGING}, property
 In order to define logging settings that are local to a subtree or
 a single item, define a =LOGGING= property in this entry.  Any
-- 
2.32.0


[-- Attachment #2: Type: text/plain, Size: 1360 bytes --]

Hi.  I continue below:

Em [2020-04-12 dom 10:45:44-0300], Jorge P. de Morais Neto escreveu:

> ** [info:org#Tracking TODO state changes]
>
> The following sentence is misplaced, interrupting the previous train of
> thought:
>
>     To record a timestamp without a note for TODO keywords configured
>     with `@', just type `C-c C-c' to enter a blank note when prompted.

I prepared the patch above to improve the organization of the respective
manual section.

> ** [[info:org#Drawers]]
>
> I don't understand the sentence
>
>        Completion over drawer keywords is also possible using ‘M-<TAB>’
>
> Could give me a simple example of drawer keyword completion?

Sorry for insisting, but can someone give me an example of what the
manual means by "Completion over drawer keywords"?

And in this kind of situation, did I do well by attaching the patch to a
normal reply in the thread, or should I have started a new thread with
an appropriate subject line?  If so, then please give me details so I do
it correctly next time.

Regards

-- 
- Disinformation flourishes because many people care about injustice
  but very few check the facts.  Ask me about <https://stallmansupport.org>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- https://www.defectivebydesign.org
- https://www.gnu.org

Re: Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Nicolas Goaziou]

Hello,

Jorge P. de Morais Neto <jorge+list@disroot.org> writes:

> I prepared the patch above to improve the organization of the respective
> manual section.

Applied. Thank you.

>> ** [[info:org#Drawers]]
>>
>> I don't understand the sentence
>>
>>        Completion over drawer keywords is also possible using ‘M-<TAB>’
>>
>> Could give me a simple example of drawer keyword completion?
>
> Sorry for insisting, but can someone give me an example of what the
> manual means by "Completion over drawer keywords"?

  :foo:
  :end:

  :f|

With point at |, M-TAB will complete the line as

                                 :foo:

> And in this kind of situation, did I do well by attaching the patch to a
> normal reply in the thread, or should I have started a new thread with
> an appropriate subject line?  If so, then please give me details so I do
> it correctly next time.

I think what you did is correct. But the other option would not be the
end of the world either. 

Regards,
-- 
Nicolas Goaziou

Re: Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Jorge P. de Morais Neto]

[-- Attachment #1: 0001-doc-org-manual.org-Drawers-Clarify-M-TAB.patch --]
[-- Type: text/x-diff, Size: 1811 bytes --]

From d3c62edf7a713278432ebe1c72e4545b8a2b84e2 Mon Sep 17 00:00:00 2001
From: "Jorge P. de Morais Neto" <jorge+git@disroot.org>
Date: Wed, 11 Aug 2021 18:43:21 -0300
Subject: [PATCH] * doc/org-manual.org (Drawers): Clarify M-TAB

Provide example of completion over drawer keywords.  Also clarify the
footnote by qualifying "windows" as "graphical".
---
 doc/org-manual.org | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index d34d33561..467644453 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -1214,7 +1214,22 @@ Org mode uses this special drawer for storing properties (see
 [[*Properties and Columns]]).  You cannot use it for anything else.
 
 Completion over drawer keywords is also possible using
-{{{kbd(M-TAB)}}}[fn:16].
+{{{kbd(M-TAB)}}}[fn:16].  For example, if the buffer contains
+
+#+begin_example
+:foo:
+:end:
+
+:f★
+#+end_example
+
+#+texinfo: @noindent
+(where ★ indicates the location of point) then {{{kbd(M-TAB)}}} will
+complete the line as
+
+#+begin_example
+:foo:★
+#+end_example
 
 Visibility cycling (see [[*Visibility Cycling]]) on the headline hides and
 shows the entry, but keep the drawer collapsed to a single line.  In
@@ -21500,8 +21515,8 @@ variable ~org-M-RET-may-split-line~.
 
 [fn:15] See ~org-list-use-circular-motion~ for a cyclic behavior.
 
-[fn:16] Many desktops intercept {{{kbd(M-TAB)}}} to switch windows.
-Use {{{kbd(C-M-i)}}} or {{{kbd(ESC TAB)}}} instead.
+[fn:16] Many desktops intercept {{{kbd(M-TAB)}}} to switch graphical
+windows.  Use {{{kbd(C-M-i)}}} or {{{kbd(ESC TAB)}}} instead.
 
 [fn:17] To insert a vertical bar into a table field, use =\vert= or,
 inside a word =abc\vert{}def=.
-- 
2.32.0


[-- Attachment #2: Type: text/plain, Size: 1216 bytes --]

Hello,

Em [2021-08-11 qua 22:50:36+0200], Nicolas Goaziou escreveu:

>> Sorry for insisting, but can someone give me an example of what the
>> manual means by "Completion over drawer keywords"?
>
>   :foo:
>   :end:
>
>   :f|
>
> With point at |, M-TAB will complete the line as
>
>                                  :foo:

Then how about the attached patch?  Note that I used a black star to
indicate the position of point---the convention in the Elisp manual.
Also, I provided a ~+#+texinfo: @noindent~ directive so the continuation
would not be indented, because it is not a new paragraph.  Please tell
whether that made sense---I know little about Texinfo and typography.

Also tell whether I am making good use of time---mine and yours.  I have
OCD and I often nitpick about details of little relevance; feedback
about that is always welcome.

Regards

-- 
- Disinformation flourishes because many people care about injustice
  but very few check the facts.  Ask me about <https://stallmansupport.org>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- Free Software Supporter: https://www.fsf.org/free-software-supporter
- If an email of mine arrives at your spam box, please notify me.

Re: Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Timothy]

[-- Attachment #1: Type: text/plain, Size: 1027 bytes --]

Hi Jorge,

> [1. text/x-diff; 0001-doc-org-manual.org-Drawers-Clarify-M-TAB.patch]…

> Then how about the attached patch?  Note that I used a black star to
> indicate the position of point—the convention in the Elisp manual.
> Also, I provided a `+#+texinfo: @noindent' directive so the continuation
> would not be indented, because it is not a new paragraph.  Please tell
> whether that made sense—I know little about Texinfo and typography.

I had a look at your patch, and it seems sensible to me 👍. I think it would be
worth merging.

> Also tell whether I am making good use of time—mine and yours.  I have
> OCD and I often nitpick about details of little relevance; feedback
> about that is always welcome.

I can’t speak for Nicolas of course, but if I may give a little feedback: IMO
improvements to the manual are always welcome — both in how easy it is to
read, and the accuracy and completeness of it. So thank you for making an effort
to improve it :)

All the best,
Timothy

Re: Bug: Small documentation errors [9.3.6 (9.3.6-29-g6a3dff-elpaplus @ /home/jorge/.emacs.d/elpa/27.0/develop/org-plus-contrib-20200406/)]

[Jorge P. de Morais Neto]

Hi Timothy!  Thank you for the patch review and for the feedback.

Regards

-- 
- Many people hate injustice but very few check the facts.  This provokes
  misinformation.  Ask me about <https://stallmansupport.org>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- https://www.defectivebydesign.org
- https://www.gnu.org