From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: Missing `Specific Header Arguments' in Manual Date: Tue, 08 May 2018 16:05:27 +0200 Message-ID: <87fu32tf88.fsf@nicolasgoaziou.fr> References: <8D4BA262-9F3F-412B-8DF1-5F6A6E3E671C@ucsd.edu> <87o9hzf3mu.fsf@nicolasgoaziou.fr> <87a7tifcme.fsf@nicolasgoaziou.fr> <87vabyv9ch.fsf@bzg.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:35534) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fG3FQ-0001pL-Mg for emacs-orgmode@gnu.org; Tue, 08 May 2018 10:05:47 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fG3FK-00053a-NS for emacs-orgmode@gnu.org; Tue, 08 May 2018 10:05:44 -0400 In-Reply-To: <87vabyv9ch.fsf@bzg.fr> (Bastien's message of "Tue, 08 May 2018 10:29:34 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Bastien Cc: emacs-orgmode , "Berry, Charles" , Kaushal Modi Hello, Bastien 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