Missing `Specific Header Arguments' in Manual

Missing `Specific Header Arguments' in Manual

[Berry, Charles]

I miss not being able to refer to a single section in the manual so I can browse the useful babel header arguments whose name, spelling, or function I have forgotten.  I guess it was re-organized out of the manual in the update to the new org formatted manual.

Is there any way to recover this?  

Or maybe add an appendix just for specific header args rather than having to hunt them down in the Main Appendix?

Chuck

Re: Missing `Specific Header Arguments' in Manual

[Nicolas Goaziou]

Hello,

"Berry, Charles" <ccberry@ucsd.edu> writes:

> I miss not being able to refer to a single section in the manual so
> I can browse the useful babel header arguments whose name, spelling,
> or function I have forgotten. I guess it was re-organized out of the
> manual in the update to the new org formatted manual.

Yes, and it took me a long while to properly put all these arguments in
a logical place instead of having them piled on top of each other.

> Is there any way to recover this?  
>
> Or maybe add an appendix just for specific header args rather than
> having to hunt them down in the Main Appendix?

You don't have to hunt them down. Within info, "i" then "header
argument". A half-decent completion mechanism will display all of them.

In the worse case, i.e., you have no decent completion mechanism, you
can go to the Main Index then "C-s header argument M-s o".

Now they are sorted, you can also search by topic. For example, if you
know the specific header argument your are looking after is related to
tangling, you can go directly to (info "(org) Extracting Source Code").

Regards,

-- 
Nicolas Goaziou

Re: Missing `Specific Header Arguments' in Manual

[Kaushal Modi]

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

Hi Nicolas,

I ran into this issue too very recently when I wanted to search for
":eval". Details below.

On Tue, May 1, 2018 at 5:50 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> Yes, and it took me a long while to properly put all these arguments in
> a logical place instead of having them piled on top of each other.
>

In the Org 9.1 version manual, it was possible to search ":eval" and find
what I was looking for. In 9.2 manual, very few of the header arguments are
documented with the colon prefix. So searching is not consistent any more.

I was able to do this earlier.. open Org Info manual, C-s :eval, keep on
C-s as it found *all hits* in the manual. Now in 9.2, the only hits are in
(org) Exporting Code Blocks, which is not very useful.

Can we prefix all the header arg references in the manual with ":" so that
while searching, I can easily find the (org) Evaluating Code Blocks node? I
was having trouble finding this node as "eval" is too generic of a string..
thankfully I remembered the "never-export" value, searched for that and
found that node.


>  You don't have to hunt them down. Within info, "i" then "header
> argument". A half-decent completion mechanism will display all of them.
>

Thanks for that tip! I guess I need to use the "i" approach more often than
the plain old C-s. But I confirm that with "i" followed by "header
argument", it presents a nice list of all arguments in the Ivy interface.

Kaushal
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2206 bytes --]

Re: Missing `Specific Header Arguments' in Manual

[Berry, Charles]

> On May 1, 2018, at 3:10 PM, Kaushal Modi <kaushal.modi@gmail.com> wrote:
> 
> Hi Nicolas,
> 
> I ran into this issue too very recently when I wanted to search for ":eval". Details below.
> 
> On Tue, May 1, 2018 at 5:50 PM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> 
> Yes, and it took me a long while to properly put all these arguments in
> a logical place instead of having them piled on top of each other.

I should have said `Thanks!' for that.

> 
> In the Org 9.1 version manual, it was possible to search ":eval" and find what I was looking for. In 9.2 manual, very few of the header arguments are documented with the colon prefix. So searching is not consistent any more.
> 
> I was able to do this earlier.. open Org Info manual, C-s :eval, keep on C-s as it found *all hits* in the manual. Now in 9.2, the only hits are in (org) Exporting Code Blocks, which is not very useful. 
> 
> Can we prefix all the header arg references in the manual with ":" so that while searching, I can easily find the (org) Evaluating Code Blocks node? I was having trouble finding this node as "eval" is too generic of a string.. thankfully I remembered the "never-export" value, searched for that and found that node.
>  
>  You don't have to hunt them down. Within info, "i" then "header
> argument". A half-decent completion mechanism will display all of them.
> 

I guess I don't have a half-decent completion mechanism - just ido. But this got me looking at info, which I do not know well enough. 

It turns out that (upper case) `I' followed by `header argument' followed by RET pops up an `Info Virtual Index' which is what I wanted. 

And this works even without any completion add-ons.


> Thanks for that tip! I guess I need to use the "i" approach more often than the plain old C-s. But I confirm that with "i" followed by "header argument", it presents a nice list of all arguments in the Ivy interface.

Yes. This expands my `info fu'. So thanks again.

Chuck

Re: Missing `Specific Header Arguments' in Manual

[Nicolas Goaziou]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> In the Org 9.1 version manual, it was possible to search ":eval" and find
> what I was looking for. In 9.2 manual, very few of the header arguments are
> documented with the colon prefix.

I removed all colon prefixes, so it is a bug if any header argument is
prefixed with a colon.

> So searching is not consistent any more.

Of course, it is. Now, you can search by topic. E.g., `eval' header
argument belongs to "Limit Code block evaluation", which is a sub-topic
of "Evaluation Code Blocks". This was clearly not possible before,
because unrelated arguments were located in the same section.

You can also search the index alphabetically.

> I was able to do this earlier.. open Org Info manual, C-s :eval, keep on
> C-s as it found *all hits* in the manual. Now in 9.2, the only hits are in
> (org) Exporting Code Blocks, which is not very useful.

C-s is a poor way to navigate through an Info document. I'd rather
improve the index than make it easier to use C-s.

> Can we prefix all the header arg references in the manual with ":" so
> that while searching, I can easily find the (org) Evaluating Code
> Blocks node?

This is a false good idea, because many index entries would have the
same prefix. Besides, many syntactic elements start with colons:
properties, tags, drawers.

OTOH, you can search for "header argument" in the main index, as you
experienced. It is much more efficient.

> I was having trouble finding this node as "eval" is too generic of a string..
> thankfully I remembered the "never-export" value, searched for that and
> found that node.

See above.

Regards,

-- 
Nicolas Goaziou

Re: Missing `Specific Header Arguments' in Manual

[Bastien]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Kaushal Modi <kaushal.modi@gmail.com> writes:
>
>> In the Org 9.1 version manual, it was possible to search ":eval" and find
>> what I was looking for. In 9.2 manual, very few of the header arguments are
>> documented with the colon prefix.
>
> I removed all colon prefixes, so it is a bug if any header argument is
> prefixed with a colon.

Why did you remove colon prefixes?

The colon is part of the header argument, so I'd thought it is natural
to include it in searches.

>> So searching is not consistent any more.
>
> Of course, it is. Now, you can search by topic. E.g., `eval' header
> argument belongs to "Limit Code block evaluation", which is a sub-topic
> of "Evaluation Code Blocks". This was clearly not possible before,
> because unrelated arguments were located in the same section.
>
> You can also search the index alphabetically.

There is a section called "Header arguments" in the new org-manual.org.

The natural expectation is for this section to list all header arguments.

Looking for ":eval" or "eval" in here will bring nothing, which is not
very natural.  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.)

What can we do to improve the manual here?

-- 
 Bastien

Re: Missing `Specific Header Arguments' in Manual

[Nicolas Goaziou]

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

Re: Missing `Specific Header Arguments' in Manual

[Bastien]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> There is a section called "Header arguments" in the new
>> org-manual.org.
>
> No, there is not.

See line 17450 in doc/org-manual.org of the current master.

-- 
 Bastien

Re: Missing `Specific Header Arguments' in Manual

[Nicolas Goaziou]

Bastien <bzg@gnu.org> writes:

> See line 17450 in doc/org-manual.org of the current master.

This is not a section, actually not in the Texinfo sense. See line 17452
in the same document. I.e., there is no node attached to it, it cannot
be accessed from "m" menu from `info', and it doesn't appear in the node
menu. IOW, there is no possible way to be confused with it when looking
for information about header arguments, because it is almost invisible.

You seem to be mixing the Org document and the ".info" file. Your
argument is:

  The natural expectation is for this section to list all header
  arguments

But this so-called section does not exist in the ".info" file. So the
expectation is wrong, at least from someone looking at the Info buffer,
which is the case we're talking about.

Re: Missing `Specific Header Arguments' in Manual

[Berry, Charles]

> On May 1, 2018, at 2:49 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> 
> Hello,
> 
> "Berry, Charles" <ccberry@ucsd.edu> writes:
> 
>> I miss not being able to refer to a single section in the manual so
>> I can browse the useful babel header arguments whose name, spelling,
>> or function I have forgotten. I guess it was re-organized out of the
>> manual in the update to the new org formatted manual.
> 
> Yes, and it took me a long while to properly put all these arguments in
> a logical place instead of having them piled on top of each other.

Comparing `org-babel-common-header-args-w-values' to the info virtual index from 'Iheader arguments', I do not see  these header args in the manual and did not find them using `M-s o' in org-manual.org: 

cmdline (not in the previous info version either)

sep

tangle-mode

wrap

Also, `exports' is indexed as `@samp{export}'.

HTH,

Chuck

Re: Missing `Specific Header Arguments' in Manual

[Nicolas Goaziou]

Hello,

"Berry, Charles" <ccberry@ucsd.edu> writes:

> cmdline (not in the previous info version either)
> sep

I'm not sure what these two are about (the :sep is not documented
either).

Besides, :cmdline doesn't seem to be used consistently everywhere. It
could probably be moved out of "ob-core.el" and re-introduced in every
Babel library actually using it.

In any case, patches welcome.

> tangle-mode

Done.

> wrap

Done.

> Also, `exports' is indexed as `@samp{export}'.

Fixed.

Thank you.

Regards,

-- 
Nicolas Goaziou

Re: Missing `Specific Header Arguments' in Manual

[Berry, Charles]

> On May 2, 2018, at 3:56 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> 
> Hello,
> 
> "Berry, Charles" <ccberry@ucsd.edu> writes:
> 
>> cmdline (not in the previous info version either)
>> sep
> 
> I'm not sure what these two are about (the :sep is not documented
> either).

Re :sep, FWIW I found this in org.texi from late 2017:

@node sep
@subsubsection @code{:sep}
@cindex @code{:sep}, src header argument

The @code{:sep} header argument is the delimiter for saving results as tables
to files (@pxref{file}) external to Org mode.  Org defaults to tab delimited
output.  The function, @code{org-open-at-point}, which is bound to @kbd{C-c
C-o}, also uses @code{:sep} for opening tabular results.

---

HTH,

Chuck

Re: Missing `Specific Header Arguments' in Manual

[Nicolas Goaziou]

Hello,

"Berry, Charles" <ccberry@ucsd.edu> writes:

> @cindex @code{:sep}, src header argument
>
> The @code{:sep} header argument is the delimiter for saving results as tables
> to files (@pxref{file}) external to Org mode.  Org defaults to tab delimited
> output.  The function, @code{org-open-at-point}, which is bound to @kbd{C-c
> C-o}, also uses @code{:sep} for opening tabular results.

Done Thank you.

Regards,

-- 
Nicolas Goaziou