Re: [O] Missing `Specific Header Arguments' in Manual

[Nicolas Goaziou]

Hello,

Bastien <address@hidden> 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