From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Bastien <bzg@gnu.org>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>,
"Berry, Charles" <ccberry@ucsd.edu>,
Kaushal Modi <kaushal.modi@gmail.com>
Subject: Re: Missing `Specific Header Arguments' in Manual
Date: Tue, 08 May 2018 16:05:27 +0200 [thread overview]
Message-ID: <87fu32tf88.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <87vabyv9ch.fsf@bzg.fr> (Bastien's message of "Tue, 08 May 2018 10:29:34 +0200")
Hello,
Bastien <bzg@gnu.org> writes:
> Why did you remove colon prefixes?
As I explained, many structural objects start with a colon. Some of them
were indexed with a colon, others were not. This is confusing. The best
solution was to remove colons from entries in index. Adding colons
everywhere would cripple the index. Now, you look for "ARCHIVE" tag, for
"LOG_INTO_DRAWER" property, and "eval" header argument. All is
consistent without pondering about syntax details that are unimportant
in this context.
> The colon is part of the header argument, so I'd thought it is natural
> to include it in searches.
See above. After thinking about it, I came to the conclusion it was not
the most natural way to search for header arguments.
> There is a section called "Header arguments" in the new
> org-manual.org.
No, there is not.
> The natural expectation is for this section to list all header
> arguments.
This is not the purpose of a manual. It should introduce concepts within
their context. For example eval header argument is introduced in the
section "Evaluating Code Blocks", which sounds... logical.
> Looking for ":eval" or "eval" in here will bring nothing, which is not
> very natural.
"here" does not exist.
> As Kaushal said, the previous listing, though perhaps inconsistent,
> helped discoverability of arguments a lot. (In general, it is good to
> have all entities of a kind listed somewhere.)
Yes, "somewhere" is usually called an index. Luckily, the new index
lists all such entities.
> What can we do to improve the manual here?
It is already improved, just use the ways described in this thread. Use
the index instead of expecting a section in the manual to collect index
entries for you. Using index to display "header arguments" is the
natural discovery tool, IMO.
As a comparison point, if I type "i eval" in the new manual, I find
a reference to the "eval" header argument. If I type "m eval" in the new
manual, I find the entry "Evaluating Code Blocks", which contains
explanations about the "eval" header argument.
In the old manual, typing "i eval" gives nothing. Typing "m eval"
provides an "eval" entry, which apparently competes with "Evaluating
Code Blocks" section, and gives no contextual information (e.g., what is
it about...).
I hope you understand the new organization is superior to the previous
one
Regards,
--
Nicolas Goaziou
next prev parent reply other threads:[~2018-05-08 14:05 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-05-01 21:34 Missing `Specific Header Arguments' in Manual Berry, Charles
2018-05-01 21:49 ` Nicolas Goaziou
2018-05-01 22:10 ` Kaushal Modi
2018-05-01 22:31 ` Berry, Charles
2018-05-02 12:47 ` Nicolas Goaziou
2018-05-08 8:29 ` Bastien
2018-05-08 14:05 ` Nicolas Goaziou [this message]
2018-05-08 16:01 ` Bastien
2018-05-08 16:28 ` Nicolas Goaziou
2018-05-01 23:05 ` Berry, Charles
2018-05-02 10:56 ` Nicolas Goaziou
2018-05-02 17:47 ` Berry, Charles
2018-05-08 23:47 ` Nicolas Goaziou
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87fu32tf88.fsf@nicolasgoaziou.fr \
--to=mail@nicolasgoaziou.fr \
--cc=bzg@gnu.org \
--cc=ccberry@ucsd.edu \
--cc=emacs-orgmode@gnu.org \
--cc=kaushal.modi@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).