* Missing `Specific Header Arguments' in Manual @ 2018-05-01 21:34 Berry, Charles 2018-05-01 21:49 ` Nicolas Goaziou 0 siblings, 1 reply; 13+ messages in thread From: Berry, Charles @ 2018-05-01 21:34 UTC (permalink / raw) To: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 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 23:05 ` Berry, Charles 0 siblings, 2 replies; 13+ messages in thread From: Nicolas Goaziou @ 2018-05-01 21:49 UTC (permalink / raw) To: Berry, Charles; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 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-01 23:05 ` Berry, Charles 1 sibling, 2 replies; 13+ messages in thread From: Kaushal Modi @ 2018-05-01 22:10 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode, Berry, Charles [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-01 22:10 ` Kaushal Modi @ 2018-05-01 22:31 ` Berry, Charles 2018-05-02 12:47 ` Nicolas Goaziou 1 sibling, 0 replies; 13+ messages in thread From: Berry, Charles @ 2018-05-01 22:31 UTC (permalink / raw) To: Kaushal Modi; +Cc: emacs-orgmode, Nicolas Goaziou > 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 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 1 sibling, 1 reply; 13+ messages in thread From: Nicolas Goaziou @ 2018-05-02 12:47 UTC (permalink / raw) To: Kaushal Modi; +Cc: emacs-orgmode, Berry, Charles 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-02 12:47 ` Nicolas Goaziou @ 2018-05-08 8:29 ` Bastien 2018-05-08 14:05 ` Nicolas Goaziou 0 siblings, 1 reply; 13+ messages in thread From: Bastien @ 2018-05-08 8:29 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode, Berry, Charles, Kaushal Modi 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-08 8:29 ` Bastien @ 2018-05-08 14:05 ` Nicolas Goaziou 2018-05-08 16:01 ` Bastien 0 siblings, 1 reply; 13+ messages in thread From: Nicolas Goaziou @ 2018-05-08 14:05 UTC (permalink / raw) To: Bastien; +Cc: emacs-orgmode, Berry, Charles, Kaushal Modi 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-08 14:05 ` Nicolas Goaziou @ 2018-05-08 16:01 ` Bastien 2018-05-08 16:28 ` Nicolas Goaziou 0 siblings, 1 reply; 13+ messages in thread From: Bastien @ 2018-05-08 16:01 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode, Berry, Charles, Kaushal Modi 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-08 16:01 ` Bastien @ 2018-05-08 16:28 ` Nicolas Goaziou 0 siblings, 0 replies; 13+ messages in thread From: Nicolas Goaziou @ 2018-05-08 16:28 UTC (permalink / raw) To: Bastien; +Cc: emacs-orgmode, Berry, Charles, Kaushal Modi 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-01 21:49 ` Nicolas Goaziou 2018-05-01 22:10 ` Kaushal Modi @ 2018-05-01 23:05 ` Berry, Charles 2018-05-02 10:56 ` Nicolas Goaziou 1 sibling, 1 reply; 13+ messages in thread From: Berry, Charles @ 2018-05-01 23:05 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode > 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-01 23:05 ` Berry, Charles @ 2018-05-02 10:56 ` Nicolas Goaziou 2018-05-02 17:47 ` Berry, Charles 0 siblings, 1 reply; 13+ messages in thread From: Nicolas Goaziou @ 2018-05-02 10:56 UTC (permalink / raw) To: Berry, Charles; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-02 10:56 ` Nicolas Goaziou @ 2018-05-02 17:47 ` Berry, Charles 2018-05-08 23:47 ` Nicolas Goaziou 0 siblings, 1 reply; 13+ messages in thread From: Berry, Charles @ 2018-05-02 17:47 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode > 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Missing `Specific Header Arguments' in Manual 2018-05-02 17:47 ` Berry, Charles @ 2018-05-08 23:47 ` Nicolas Goaziou 0 siblings, 0 replies; 13+ messages in thread From: Nicolas Goaziou @ 2018-05-08 23:47 UTC (permalink / raw) To: Berry, Charles; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2018-05-08 23:47 UTC | newest] Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 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 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
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).