Re: [O] Bug: second batch of small documentation problems [9.0 (9.0-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/)]

[Nicolas Goaziou]

Hello,

Jorge Morais Neto <address@hidden> writes:

> Finally the second batch I promised.

Thank you.

> - org-table-convert-region docstring is less complete than the manual\\
>   The docstring contains the line:
>
>   #+BEGIN_QUOTE
>   integer  When a number, use that many spaces as field separator
>   #+END_QUOTE
>
>
>   [[info:org#Built-in table editor]] says:
>
>   #+BEGIN_QUOTE
>   a numeric argument N indicates that at least N consecutive spaces, or
>   alternatively a TAB will be the separator.
>   #+END_QUOTE
>
>   In the latter, notice the "or alternatively a TAB".  I believe the docstring
>   should be complete, so please add this information.

Fixed.

> - org-archive-to-archive-sibling ARCHIVE_TIME property\\
>   org-archive-to-archive-sibling adds an ARCHIVE_TIME property.This should be
>   documented in the docstring

Done.

> and probably also in the manual.

I'm not sure it belongs to the manual, as it is more of an
implementation detail. For the time being, I don't add it.

> - [[info:org#The very busy C-c C-c key]]
>
>   #+BEGIN_QUOTE
>    If the current buffer is a capture buffer, close the note and file it.
>   With a prefix argument, file it, without further interaction, to the
>   default location.
>   #+END_QUOTE
>
>   Actually, according to [[info:org#Using capture]] and to my quick test,
>   C-c C-c restores the original window configuration, /and the effect of C-u 
> is
>   to make it also jump to the captured item/.

Fixed.

> - org-match-sparse-tree’s docstring omits it can also match
> properties.

Fixed.

> - [[info:org#Setting tags]] should inform that tag letters for the single-key
>   interface are case-sensitive.  In "For this to work well you should assign
>   unique letters to most of your commonly used tags.", replace "assign unique
>   letters" → "assign unique letters (case-sensitive)".  After "In this
>   interface, you can use the following keys:", please write "a-zA-Z" instead 
> of
>   "a-z".  Finally, in the docstring of org-tag-alist, please replace "SELECT 
> is
>   a character" → "SELECT is a case-sensitive letter".

Done.

> - org-capture’s docstring could mention ID creation\\
>   org-capture creates an ID property if org-id-link-to-org-use-id is set to t.
>   This is already documented in that option’s docstring, but perhaps it should
>   also be documented in org-capture’s docstring and [[info:org#Using 
> capture]].
>   The reason is that if a user is surprised that org-capture created an ID
>   property, he will look in org-capture’s docstring or perhaps in the manual
>   section.  He may not remember to check org-id-link-to-org-use-id’s
>   docstring

`org-capture' itself doesn't check `org-id-link-to-org-use-id' so it
would be confusing to write about it in the docstring. I didn't find an
adequate location for this (`org-capture-templates' maybe), so I didn't
change anything here.

> - org-startup-folded’s docstring misreports the default value of
>   org-agenda-inhibit-startup.  The docstring’s last paragraph need changing.

Done.

> - org-agenda-todo-ignore-deadlines’ docstring about ’far
>   The documentation of 'far says:
>
>   #+BEGIN_QUOTE
>   Dont show TODO entries where a deadline has been defined, but the deadline
>   is not near.  This is useful if you dont want to use the todo list to figure
>   out what to do now.
>   #+END_QUOTE
>
>   I do not understand this reasoning.

Fixed.

> - I believe that many people use .emacs.d/init.el instead of .emacs.  To 
> better
>   reflect this reality, should not Org’s manual use the expression "Emacs init
>   file" instead of ".emacs"?

I agree. Done.

> - Typos and small corrections:
>   - Docstring of org-agenda-show-inherited-tags
>
>     #+BEGIN_QUOTE
>     when the value of org-agenda-use-tag-inheritance has been taken into
>     account.
>     #+END_QUOTE
>
>     "has been taken into account." → "enables tag inheritance for the given
>     agenda type."

Done.

>   - Docstring of org-agenda-week-view\\
>     In "Switch to daily view for agenda", "daily" → "weekly".

Done.

Regards,

-- 
Nicolas Goaziou