all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Confused about the explanation for 'org-cycle'
@ 2017-09-18 14:04 Alain.Cochard
  2017-09-19  5:08 ` Matt Lundin
  0 siblings, 1 reply; 27+ messages in thread
From: Alain.Cochard @ 2017-09-18 14:04 UTC (permalink / raw)
  To: emacs-orgmode; +Cc: Alain Cochard


Hello.

In section "2.3.1 Global and local cycling" of the manual I read:


     `<TAB>'     (`org-cycle')
          _Subtree cycling_: Rotate current subtree among the states

               ,-> FOLDED -> CHILDREN -> SUBTREE --.
               '-----------------------------------'

          The cursor must be on a headline for this to work(1).  When the
          cursor is at the beginning of the buffer and the first line is not
          a headline, then <TAB> actually runs global cycling (see
          below)(2).

with the footnote being

     (2) see the option `org-cycle-global-at-bob'.


If I use Org Mode without any customization, then, when using <TAB>
"When the cursor is at the beginning of the buffer and the first line
is not a headline", absolutely nothing is done.

Sure, this is consistent with the help page of variable
org-cycle-global-at-bob which says that "When this option is nil,
don't do anything special at the beginning of the buffer", together
with the fact that, without any customization, org-cycle-global-at-bob
is 'nil'.

But I find this very confusing, at least for the beginner, who is
unlikely to enquire right away about the possible values of
org-cycle-global-at-bob.

Or perhaps I am missing something at the English level?

Regards,
alain


-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-18 14:04 Confused about the explanation for 'org-cycle' Alain.Cochard
@ 2017-09-19  5:08 ` Matt Lundin
  2017-09-20 10:57   ` Nicolas Goaziou
  0 siblings, 1 reply; 27+ messages in thread
From: Matt Lundin @ 2017-09-19  5:08 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

I agree that this is confusing. I examined the org repository history,
and it seems that both the documentation and the variable go all the way
back to 2007. I believe the default value of the variable was changed to
nil, but the documentation was not updated accordingly.  

Matt

Alain.Cochard@unistra.fr writes:

> Hello.
>
> In section "2.3.1 Global and local cycling" of the manual I read:
>
>
>      `<TAB>'     (`org-cycle')
>           _Subtree cycling_: Rotate current subtree among the states
>
>                ,-> FOLDED -> CHILDREN -> SUBTREE --.
>                '-----------------------------------'
>
>           The cursor must be on a headline for this to work(1).  When the
>           cursor is at the beginning of the buffer and the first line is not
>           a headline, then <TAB> actually runs global cycling (see
>           below)(2).
>
> with the footnote being
>
>      (2) see the option `org-cycle-global-at-bob'.
>
>
> If I use Org Mode without any customization, then, when using <TAB>
> "When the cursor is at the beginning of the buffer and the first line
> is not a headline", absolutely nothing is done.
>
> Sure, this is consistent with the help page of variable
> org-cycle-global-at-bob which says that "When this option is nil,
> don't do anything special at the beginning of the buffer", together
> with the fact that, without any customization, org-cycle-global-at-bob
> is 'nil'.
>
> But I find this very confusing, at least for the beginner, who is
> unlikely to enquire right away about the possible values of
> org-cycle-global-at-bob.
>
> Or perhaps I am missing something at the English level?
>
> Regards,
> alain

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-19  5:08 ` Matt Lundin
@ 2017-09-20 10:57   ` Nicolas Goaziou
  2017-09-26  8:54     ` Alain.Cochard
  0 siblings, 1 reply; 27+ messages in thread
From: Nicolas Goaziou @ 2017-09-20 10:57 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

Hello,

Matt Lundin <mdl@imapmail.org> writes:

> I agree that this is confusing. I examined the org repository history,
> and it seems that both the documentation and the variable go all the way
> back to 2007. I believe the default value of the variable was changed to
> nil, but the documentation was not updated accordingly.

I rewrote the part about `org-cycle-global-at-bob'. Hopefully it is
clearer now.

Thank you.

Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-20 10:57   ` Nicolas Goaziou
@ 2017-09-26  8:54     ` Alain.Cochard
  2017-09-26 10:41       ` Nicolas Goaziou
  0 siblings, 1 reply; 27+ messages in thread
From: Alain.Cochard @ 2017-09-26  8:54 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard

Nicolas Goaziou writes on Wed 20 Sep 2017 12:57:
 > Hello,
 > 
 > Matt Lundin <mdl@imapmail.org> writes:
 > [...]
 > I rewrote the part about `org-cycle-global-at-bob'. Hopefully it is
 > clearer now.

Thank you, Nicolas and Matt, for the feedback.

I updated to version org-20170925 and what I read now:

   You can run global cycling using <TAB> only if point is at the very
   beginning of the buffer and `org-cycle-global-at-bob' is set to a
   non-`nil' value.

is indeed fully clear to me concerning the issue I raised.

But now, compared to the previous version:

   When the cursor is at the beginning of the buffer and the first
   line is not a headline, then <TAB> actually runs global cycling

it is not clear to me why the mention "and the first line is not a
headline" has been suppressed.  Perhaps it has been replaced by the
addition of the word "very"?  If so, I feel it is maybe a little bit
less explicit.

Regards,
Alain

-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-26  8:54     ` Alain.Cochard
@ 2017-09-26 10:41       ` Nicolas Goaziou
  2017-09-26 12:48         ` Alain.Cochard
  0 siblings, 1 reply; 27+ messages in thread
From: Nicolas Goaziou @ 2017-09-26 10:41 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

Hello,

Alain.Cochard@unistra.fr writes:

> But now, compared to the previous version:
>
>    When the cursor is at the beginning of the buffer and the first
>    line is not a headline, then <TAB> actually runs global cycling
>
> it is not clear to me why the mention "and the first line is not a
> headline" has been suppressed.

I traded completeness for clarity. 

The reasoning is that the description about a pathological case -- here,
the first line of the buffer being a heading -- belongs to variable's
docstring, not to the manual.

We can add a footnote about that case, but even a footnote impedes
clarity.

Of course, if you have a clear wording that includes that pathological
case, I'll happily use it.

Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-26 10:41       ` Nicolas Goaziou
@ 2017-09-26 12:48         ` Alain.Cochard
  2017-09-28 13:44           ` org-list-empty-line-terminates-plain-lists removed but still mentioned in the manual Alain.Cochard
  2017-09-28 14:31           ` Confused about the explanation for 'org-cycle' Nicolas Goaziou
  0 siblings, 2 replies; 27+ messages in thread
From: Alain.Cochard @ 2017-09-26 12:48 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard

Nicolas Goaziou writes on Tue 26 Sep 2017 12:41:
 > Hello,
 > 
 > Alain.Cochard@unistra.fr writes:
 > 
 > > But now, compared to the previous version:
 > >
 > >    When the cursor is at the beginning of the buffer and the
 > >    first line is not a headline, then <TAB> actually runs global
 > >    cycling
 > >
 > > it is not clear to me why the mention "and the first line is not
 > > a headline" has been suppressed.
 > 
 > I traded completeness for clarity. 
 > 
 > The reasoning is that the description about a pathological case --
 > here, the first line of the buffer being a heading -- belongs to
 > variable's docstring, not to the manual.
 > 
 > We can add a footnote about that case, but even a footnote impedes
 > clarity.
 > 
 > Of course, if you have a clear wording that includes that
 > pathological case, I'll happily use it.

OK, I understand your point, although I probably cannot fully
appreciate it because I do not know what a "docstring" is.

As for the wording, I have nothing ecstatic to propose, but -- as a
beginner and trying to think like one who is reading the manual for
the first time while experimenting -- I would have been happy with
something like:

   You can run global cycling using <TAB> only if point is at the very
   beginning of the buffer (not being a headline) and
   `org-cycle-global-at-bob' is set to a non-`nil' value.


More generally, I cannot remember the number of times when I read the
manual, do not understand it, am essentially sure that it is wrongly
phrased but (just in case) spend a (too) long time searching the Web
before complaining to the list, to finally realize that "Ah OK, the
manual is fully correct."

In other words, the manual is often too concise/elegant for the
(admittedly not very smart) beginner that I am, and I would favor
completeness -- with footnotes, dumb examples to get started, more
cross-references, even repetitions -- over clarity.

But maybe that's just me...

Regards,
a.



-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* org-list-empty-line-terminates-plain-lists removed but still mentioned in the manual
  2017-09-26 12:48         ` Alain.Cochard
@ 2017-09-28 13:44           ` Alain.Cochard
  2017-09-28 14:07             ` Nicolas Goaziou
  2017-09-28 14:31           ` Confused about the explanation for 'org-cycle' Nicolas Goaziou
  1 sibling, 1 reply; 27+ messages in thread
From: Alain.Cochard @ 2017-09-28 13:44 UTC (permalink / raw)
  To: emacs-orgmode; +Cc: alain.cochard


Hello.

If I understand correctly, the thread
https://lists.gnu.org/archive/html/emacs-orgmode/2014-07/msg00678.html
seems to say that variable
'org-list-empty-line-terminates-plain-lists' has been removed;
consistently, querying it with 'C-h v' fails.

Yet, it is still mentioned in the manual, in section 2.7 (and in
the Variable index):

2.7 Plain lists
===============

[...]

   A list ends whenever every item has ended, which means before any
line less or equally indented than items at top level.  It also ends
before two blank lines(5).

[...]

   (5) See also `org-list-empty-line-terminates-plain-lists'.


-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: org-list-empty-line-terminates-plain-lists removed but still mentioned in the manual
  2017-09-28 13:44           ` org-list-empty-line-terminates-plain-lists removed but still mentioned in the manual Alain.Cochard
@ 2017-09-28 14:07             ` Nicolas Goaziou
  0 siblings, 0 replies; 27+ messages in thread
From: Nicolas Goaziou @ 2017-09-28 14:07 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

Hello,

Alain.Cochard@unistra.fr writes:

> If I understand correctly, the thread
> https://lists.gnu.org/archive/html/emacs-orgmode/2014-07/msg00678.html
> seems to say that variable
> 'org-list-empty-line-terminates-plain-lists' has been removed;
> consistently, querying it with 'C-h v' fails.
>
> Yet, it is still mentioned in the manual, in section 2.7 (and in
> the Variable index):
>
> 2.7 Plain lists
> ===============
>
> [...]
>
>    A list ends whenever every item has ended, which means before any
> line less or equally indented than items at top level.  It also ends
> before two blank lines(5).
>
> [...]
>
>    (5) See also `org-list-empty-line-terminates-plain-lists'.

Fixed. Thank you.

Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-26 12:48         ` Alain.Cochard
  2017-09-28 13:44           ` org-list-empty-line-terminates-plain-lists removed but still mentioned in the manual Alain.Cochard
@ 2017-09-28 14:31           ` Nicolas Goaziou
  2017-09-28 15:29             ` Robert Horn
  2017-09-28 21:04             ` Alain.Cochard
  1 sibling, 2 replies; 27+ messages in thread
From: Nicolas Goaziou @ 2017-09-28 14:31 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

Hello,

Alain.Cochard@unistra.fr writes:

> As for the wording, I have nothing ecstatic to propose, but -- as a
> beginner and trying to think like one who is reading the manual for
> the first time while experimenting -- I would have been happy with
> something like:
>
>    You can run global cycling using <TAB> only if point is at the very
>    beginning of the buffer (not being a headline) and
>    `org-cycle-global-at-bob' is set to a non-`nil' value.

Fixed. Thank you.

> More generally, I cannot remember the number of times when I read the
> manual, do not understand it,

This is exactly where the manual fails. What is the point of an
exhaustive, yet not understandable, manual?

> In other words, the manual is often too concise/elegant

Alas, it is not. See above.

> for the
> (admittedly not very smart) beginner that I am, and I would favor
> completeness -- with footnotes, dumb examples to get started, more
> cross-references, even repetitions -- over clarity.

Completeness is not possible. For example, we do not document every
variable in the manual. Besides, when reading a pile of special rules
for special cases, the reader may lose focus and miss the whole concept.

BTW, a "docstring" is the documentation you get when using, e.g., `C-h
v' or `C-h f'.

Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-28 14:31           ` Confused about the explanation for 'org-cycle' Nicolas Goaziou
@ 2017-09-28 15:29             ` Robert Horn
  2017-09-28 16:10               ` Kyle Meyer
  2017-09-28 21:04             ` Alain.Cochard
  1 sibling, 1 reply; 27+ messages in thread
From: Robert Horn @ 2017-09-28 15:29 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard


Nicolas Goaziou writes:

> Completeness is not possible. For example, we do not document every
> variable in the manual. Besides, when reading a pile of special rules
> for special cases, the reader may lose focus and miss the whole concept.
>
> BTW, a "docstring" is the documentation you get when using, e.g., `C-h
> v' or `C-h f'.
>

Actually, an effective way to deal with this is to have two sections: "All
external org functions" and "All external org variables" that merely lists them
all alphabetically, and begins with a short paragraph on what a
doc-string is and how to get it for these.

This might also be a place to put a short paragraph about how internal org
functions and variables are identified, and why it is a good idea to
avoid using them in added features.  E.g., the fact that they may be
replaced, removed, or revised drastically by subsequent org releases.

It's not quite as simple as doing a search for defun, pruning, and
sorting, but it shouldn't be much more than that.

This would probably help new users a lot.

R Horn

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-28 15:29             ` Robert Horn
@ 2017-09-28 16:10               ` Kyle Meyer
  2017-09-28 16:17                 ` Eric S Fraga
  0 siblings, 1 reply; 27+ messages in thread
From: Kyle Meyer @ 2017-09-28 16:10 UTC (permalink / raw)
  To: Robert Horn, Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard

Robert Horn <rjhorn@alum.mit.edu> writes:

> Nicolas Goaziou writes:
>
>> Completeness is not possible. For example, we do not document every
>> variable in the manual. Besides, when reading a pile of special rules
>> for special cases, the reader may lose focus and miss the whole concept.
>>
>> BTW, a "docstring" is the documentation you get when using, e.g., `C-h
>> v' or `C-h f'.
>
> Actually, an effective way to deal with this is to have two sections: "All
> external org functions" and "All external org variables" that merely lists them
> all alphabetically, and begins with a short paragraph on what a
> doc-string is and how to get it for these.

I don't think maintaining a list of all Org's user options or commands
is a good idea.  It is better to point users to commands like
apropos-user-option and apropos-command.

-- 
Kyle

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-28 16:10               ` Kyle Meyer
@ 2017-09-28 16:17                 ` Eric S Fraga
  0 siblings, 0 replies; 27+ messages in thread
From: Eric S Fraga @ 2017-09-28 16:17 UTC (permalink / raw)
  To: Kyle Meyer; +Cc: emacs-orgmode, Robert Horn, Nicolas Goaziou, Alain.Cochard

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

On Thursday, 28 Sep 2017 at 12:10, Kyle Meyer wrote:
> I don't think maintaining a list of all Org's user options or commands
> is a good idea.  It is better to point users to commands like
> apropos-user-option and apropos-command.

Or even "C-h f org- TAB" or "C-h v org- TAB" to see all org functions
and variables respectively...

The help system (including apropos) in Emacs is underutilised, I
think.  It is initially daunting (as is Emacs in general) but worth
learning.

-- 
: Eric S Fraga via Emacs 27.0.50, Org release_9.1.1-78-gfbf47c

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-28 14:31           ` Confused about the explanation for 'org-cycle' Nicolas Goaziou
  2017-09-28 15:29             ` Robert Horn
@ 2017-09-28 21:04             ` Alain.Cochard
  2017-09-28 21:22               ` Josiah Schwab
  2017-09-28 21:30               ` Nicolas Goaziou
  1 sibling, 2 replies; 27+ messages in thread
From: Alain.Cochard @ 2017-09-28 21:04 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard


Thanks for your answer.

Nicolas Goaziou writes on Thu 28 Sep 2017 16:31:

 > > More generally, I cannot remember the number of times when I read
 > > the manual, do not understand it,
 > 
 > This is exactly where the manual fails. What is the point of an
 > exhaustive, yet not understandable, manual?

It looks like I did not make myself clear (or I don't understand your
sentence above): the "number of times" to which I was referring are
when the manual is /not exhaustive enough/ (to me, that is).

 > > for the (admittedly not very smart) beginner that I am, and I
 > > would favor completeness -- with footnotes, dumb examples to get
 > > started, more cross-references, even repetitions -- over clarity.
 > 
 > Completeness is not possible. For example, we do not document every
 > variable in the manual. Besides, when reading a pile of special
 > rules for special cases, the reader may lose focus and miss the
 > whole concept.

I guess the degree of expected completeness varies between
individuals...  This being said, I contend that it is often possible
to add a lot of completeness mostly without altering clarity, using an
appropriate organization (like more in-depth sections or examples
sections).  (In fact, it seems to me that this is what is already
often done.)

Precisely, regarding variable documentation, I remember that you
already made your point in an earlier email, advocating the use of
customize-group; while I certainly do not argue about its usefulness
for some purposes, for me it is often much less convenient than
exhaustive variable documentation would be.

I have a fresh example in mind to illustrate my point: this afternoon,
I was looking for org-blank-before-new-entry.  I vaguely remembered it
existed and was searching the manual (from Info) with the regexps
'blank' and 'list'.  Had the variable been mentioned, I would have
found it within seconds; by contrast I can't imagine how much time I
would need using customize-group...  And, in this case, I don't see
how having a separate section (e.g., an appendix, much like the
Variable section), with all variables documented, would remove the
least bit of clarity.

Also, I am aware that there exist at the Worg site many tutorials
which give more in-depth documentation on specific topics.  Those
tutorials are great in general.  Nevertheless, I often observe that,
by contrast with the manual which is meant to be up-to-date, they are
obsolete in some respect, which makes them difficult for me to use in
order to get started.


 > BTW, a "docstring" is the documentation you get when using, e.g.,
 > `C-h v' or `C-h f'.

Thank you.  In retrospect, I realize I should have looked it up
myself...


Regards,
a.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-28 21:04             ` Alain.Cochard
@ 2017-09-28 21:22               ` Josiah Schwab
  2017-09-28 21:30               ` Nicolas Goaziou
  1 sibling, 0 replies; 27+ messages in thread
From: Josiah Schwab @ 2017-09-28 21:22 UTC (permalink / raw)
  To: alain.cochard; +Cc: emacs-orgmode, Nicolas Goaziou

Hi Alain,

> I have a fresh example in mind to illustrate my point: this afternoon,
> I was looking for org-blank-before-new-entry.  I vaguely remembered it
> existed and was searching the manual (from Info) with the regexps
> 'blank' and 'list'.  Had the variable been mentioned, I would have
> found it within seconds; by contrast I can't imagine how much time I
> would need using customize-group...

As pointed out by Kyle, try M-x apropos-user-option then enter
org-*blank* and you'll be there in seconds.

Josiah

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-28 21:04             ` Alain.Cochard
  2017-09-28 21:22               ` Josiah Schwab
@ 2017-09-28 21:30               ` Nicolas Goaziou
  2017-10-05  8:17                 ` Alain.Cochard
  1 sibling, 1 reply; 27+ messages in thread
From: Nicolas Goaziou @ 2017-09-28 21:30 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

Alain.Cochard@unistra.fr writes:

> I have a fresh example in mind to illustrate my point: this afternoon,
> I was looking for org-blank-before-new-entry.  I vaguely remembered it
> existed and was searching the manual (from Info) with the regexps
> 'blank' and 'list'.  Had the variable been mentioned, I would have
> found it within seconds; by contrast I can't imagine how much time I
> would need using customize-group...

A few seconds... type "org blank" in the search bar, click "Search" and
it is there.

Also, 

  M-x apropos-variable RET org blank list RET

If you use Helm, 

  F1 v org blank

is fast too.

> And, in this case, I don't see
> how having a separate section (e.g., an appendix, much like the
> Variable section), with all variables documented, would remove the
> least bit of clarity.

There are already many ways in Emacs to find a variable. I'm not
convinced that adding such an appendix would be worth the trouble
creating and maintaining it. 

As another data point, Emacs' manual doesn't contain an exhaustive
variable section either.

Regards,

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: Confused about the explanation for 'org-cycle'
  2017-09-28 21:30               ` Nicolas Goaziou
@ 2017-10-05  8:17                 ` Alain.Cochard
  2017-11-10 17:23                   ` How to use case sensitive org-search-view? Alain.Cochard
  0 siblings, 1 reply; 27+ messages in thread
From: Alain.Cochard @ 2017-10-05  8:17 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard

Nicolas Goaziou writes on Thu 28 Sep 2017 23:30:

 > There are already many ways in Emacs to find a variable. I'm not
 > convinced that adding such an appendix would be worth the trouble
 > creating and maintaining it.

 > As another data point, Emacs' manual doesn't contain an exhaustive
 > variable section either.

Fair enough.  So lack of such an appendix was not a good example of
excess of conciseness of the manual.

Thanks (to you and others) for the tips on how to get variables'
documentation.  I indeed should get used to these other methods.


-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* How to use case sensitive org-search-view?
  2017-10-05  8:17                 ` Alain.Cochard
@ 2017-11-10 17:23                   ` Alain.Cochard
  2017-11-14 14:26                     ` Matt Lundin
  0 siblings, 1 reply; 27+ messages in thread
From: Alain.Cochard @ 2017-11-10 17:23 UTC (permalink / raw)
  To: emacs-orgmode; +Cc: Alain Cochard


Hello.  Sorry about this seemingly basic question, but I spent several
hours (literally) googling and experimenting without any progress...

Suppose I have an org file with

* FOO
* foo

I would like to use org-search-view (C-c a s) so as to (say) list only
the first entry.

Among other things I tried using +FOO, +"FOO", +{FOO}, +{\bFOO\b},
with case-fold-search being t or nil, with several emacs+org versions,
but each time it lists both headlines.

Is there a way to perform what I want?

Thank you.
Alain

PS: by contrast, 'C-c a / FOO' does only list the 1st entry.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-10 17:23                   ` How to use case sensitive org-search-view? Alain.Cochard
@ 2017-11-14 14:26                     ` Matt Lundin
  2017-11-14 15:30                       ` Alain.Cochard
  2017-11-14 20:35                       ` Nicolas Goaziou
  0 siblings, 2 replies; 27+ messages in thread
From: Matt Lundin @ 2017-11-14 14:26 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

Alain.Cochard@unistra.fr writes:

> Hello.  Sorry about this seemingly basic question, but I spent several
> hours (literally) googling and experimenting without any progress...
>
> Suppose I have an org file with
>
> * FOO
> * foo
>
> I would like to use org-search-view (C-c a s) so as to (say) list only
> the first entry.
>
> Among other things I tried using +FOO, +"FOO", +{FOO}, +{\bFOO\b},
> with case-fold-search being t or nil, with several emacs+org versions,
> but each time it lists both headlines.
>
> Is there a way to perform what I want?

Unfortunately, it looks like org-search-view is hard-coded to be
case-insensitive. I think a very hackish workaround would be to advise
org-search-view to create and then remove an "around" advice that wraps
re-search-forward in a "let" declaration setting case-fold-search to
nil. But this would be a fairly horrific hack.

In the long run, I believe the Org Mode code would need to be changed to
make this customizable.

Best,
Matt

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-14 14:26                     ` Matt Lundin
@ 2017-11-14 15:30                       ` Alain.Cochard
  2017-11-14 20:35                       ` Nicolas Goaziou
  1 sibling, 0 replies; 27+ messages in thread
From: Alain.Cochard @ 2017-11-14 15:30 UTC (permalink / raw)
  To: Matt Lundin; +Cc: emacs-orgmode, Alain.Cochard

Matt Lundin writes on Tue 14 Nov 2017 08:26:

 > > Suppose I have an org file with
 > >
 > > * FOO
 > > * foo
 > >
 > > I would like to use org-search-view (C-c a s) so as to (say) list
 > > only the first entry.

 > Unfortunately, it looks like org-search-view is hard-coded to be
 > case-insensitive. I think a very hackish workaround would be to
 > advise org-search-view to create and then remove an "around" advice
 > that wraps re-search-forward in a "let" declaration setting
 > case-fold-search to nil. But this would be a fairly horrific hack.
 > 
 > In the long run, I believe the Org Mode code would need to be
 > changed to make this customizable.

In the meantime, shouldn't this "glitch" be mentioned in the manual?

The manual does say that 'C-c a s'

    Create a list of entries selected by a boolean expression of
    keywords and/or regular expressions [...]

Same problem for the 'C-c a s' minibuffer prompt:

    Phrase or [+-]Word/{Regexp}

and the subsequent

    Press `[', `]' to add/sub word, `{', `}' to add/sub regexp


I also realized that, consistently, using +{[[:upper:]]+o}, also lists
both entries.


Finally, trying to narrow the FOO + foo search results using '=':

    `=     (`org-agenda-filter-by-regexp')'
        Filter the agenda view by a regular expression: only show
        agenda entries matching the regular expression the user
        entered.

and typing explicitly 'FOO' fails accordingly.


The tutorial
http://orgmode.org/worg/org-tutorials/advanced-searching.html does not
seem to mention this point either.


Anyway, thanks you very much for your time and feed back.

Regards
a.

PS: considering "horrific hack", I think you meant "In the /short/
run...", but I'm sure the Org developpers have understood it correctly
:-)


-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-14 14:26                     ` Matt Lundin
  2017-11-14 15:30                       ` Alain.Cochard
@ 2017-11-14 20:35                       ` Nicolas Goaziou
  2017-11-14 20:55                         ` Tim Cross
  2017-11-15 10:49                         ` Alain.Cochard
  1 sibling, 2 replies; 27+ messages in thread
From: Nicolas Goaziou @ 2017-11-14 20:35 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

Hello,

Matt Lundin <mdl@imapmail.org> writes:

> Alain.Cochard@unistra.fr writes:
>
>> Hello. Sorry about this seemingly basic question, but I spent several
>> hours (literally) googling and experimenting without any progress...
>>
>> Suppose I have an org file with
>>
>> * FOO * foo
>>
>> I would like to use org-search-view (C-c a s) so as to (say) list
>> only the first entry.
>>
>> Among other things I tried using +FOO, +"FOO", +{FOO}, +{\bFOO\b},
>> with case-fold-search being t or nil, with several emacs+org
>> versions, but each time it lists both headlines.
>>
>> Is there a way to perform what I want?
>
> Unfortunately, it looks like org-search-view is hard-coded to be
> case-insensitive. I think a very hackish workaround would be to advise
> org-search-view to create and then remove an "around" advice that
> wraps re-search-forward in a "let" declaration setting
> case-fold-search to nil. But this would be a fairly horrific hack.
>
> In the long run, I believe the Org Mode code would need to be changed
> to make this customizable.

Note that there is `org-occur-case-fold-search'.

We could implement something similar with, e.g.,
`org-agenda-search-view-case-fold-search'. Or maybe use a variable for
every search related function in Org: `org-case-fold-search'.

WDYT?

 Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-14 20:35                       ` Nicolas Goaziou
@ 2017-11-14 20:55                         ` Tim Cross
  2017-11-15 14:02                           ` Nicolas Goaziou
  2017-11-15 10:49                         ` Alain.Cochard
  1 sibling, 1 reply; 27+ messages in thread
From: Tim Cross @ 2017-11-14 20:55 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard


my 2 cents would vote for a variable which manages case folding. This
would be in-line with how isearch works and something familiar to most
Emacs users. I also prefer a single function which behaves differently
depending on a config variable setting over separate functions as I
think it makes key binding easier (though admittedly, it is trivial to
define a lambda which selects between different functions depending on
the setting of a config variable or prefix arg etc ).

Tim

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Matt Lundin <mdl@imapmail.org> writes:
>
>> Alain.Cochard@unistra.fr writes:
>>
>>> Hello. Sorry about this seemingly basic question, but I spent several
>>> hours (literally) googling and experimenting without any progress...
>>>
>>> Suppose I have an org file with
>>>
>>> * FOO * foo
>>>
>>> I would like to use org-search-view (C-c a s) so as to (say) list
>>> only the first entry.
>>>
>>> Among other things I tried using +FOO, +"FOO", +{FOO}, +{\bFOO\b},
>>> with case-fold-search being t or nil, with several emacs+org
>>> versions, but each time it lists both headlines.
>>>
>>> Is there a way to perform what I want?
>>
>> Unfortunately, it looks like org-search-view is hard-coded to be
>> case-insensitive. I think a very hackish workaround would be to advise
>> org-search-view to create and then remove an "around" advice that
>> wraps re-search-forward in a "let" declaration setting
>> case-fold-search to nil. But this would be a fairly horrific hack.
>>
>> In the long run, I believe the Org Mode code would need to be changed
>> to make this customizable.
>
> Note that there is `org-occur-case-fold-search'.
>
> We could implement something similar with, e.g.,
> `org-agenda-search-view-case-fold-search'. Or maybe use a variable for
> every search related function in Org: `org-case-fold-search'.
>
> WDYT?
>
>  Regards,


-- 
Tim Cross

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-14 20:35                       ` Nicolas Goaziou
  2017-11-14 20:55                         ` Tim Cross
@ 2017-11-15 10:49                         ` Alain.Cochard
  2017-11-15 11:55                           ` Nicolas Goaziou
  1 sibling, 1 reply; 27+ messages in thread
From: Alain.Cochard @ 2017-11-15 10:49 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard

Nicolas Goaziou writes on Tue 14 Nov 2017 21:35:

 > Matt Lundin <mdl@imapmail.org> writes:
 > 
 > > Alain.Cochard@unistra.fr writes:

 > >> Suppose I have an org file with
 > >>
 > >> * FOO
 > >> * foo
 > >>
 > >> I would like to use org-search-view (C-c a s) so as to (say) list
 > >> only the first entry.
 > >> [...]
 > >> Is there a way to perform what I want?

 > > Unfortunately, it looks like org-search-view is hard-coded to be
 > > case-insensitive. I think a very hackish workaround would be to advise
 > > org-search-view to create and then remove an "around" advice that
 > > wraps re-search-forward in a "let" declaration setting
 > > case-fold-search to nil. But this would be a fairly horrific hack.
 > >
 > > In the long run, I believe the Org Mode code would need to be changed
 > > to make this customizable.


 > Note that there is `org-occur-case-fold-search'.

Thanks for pointing this out.  But boy is it complicated:

I have:

   org-occur-case-fold-search is a variable defined in `org.el'.
   Its value is t

   Documentation:
   Non-nil means `org-occur' should be case-insensitive.
   If set to `smart' the search will be case-insensitive only if it
   doesn't specify any upper case character.

and indeed, if I use

   M-x org-occur <RET> FOO

in my FOO/foo buffer, both instances are found.

But it does not seem to apply to multi-occur, which 'C-c a /' is said
to use: both 'C-c a /' and 'M-x multi-occur' for 'FOO' only list
'FOO'...

 > We could implement something similar with, e.g.,
 > `org-agenda-search-view-case-fold-search'. Or maybe use a variable for
 > every search related function in Org: `org-case-fold-search'.
 > 
 > WDYT?

From my (user) point of view, I would expect that what is supposed to
be a regexp behaves like a regexp, and in a consistent way for all
cases (with 'C-c a s', when filtering with
org-agenda-filter-by-regexp, etc.).  I would even expect a regexp
search within an Org buffer to behave exactly like a regexp search
within a plain emacs buffer, but I would understand if this not
reasonable to ask for.

Regards,
a.

PS: in the org-occur docstring:

   org-occur is an interactive compiled Lisp function in `org.el'.

   (org-occur REGEXP &optional KEEP-PREVIOUS CALLBACK)

   Make a compact tree which shows all matches of REGEXP.

   The tree will show the lines where the regexp matches, and any
   other context defined in `org-show-context-detail', which see.

the last sentence above looks grammatically/syntactically funny to me.
Maybe this is because of my insufficient level in English -- I just
don't understand what "which see" is supposed to mean.  If the English
is indeed correct, maybe a reformulation would be in order, for the
sake of non native people.






-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-15 10:49                         ` Alain.Cochard
@ 2017-11-15 11:55                           ` Nicolas Goaziou
  2017-11-15 12:35                             ` Alain.Cochard
  0 siblings, 1 reply; 27+ messages in thread
From: Nicolas Goaziou @ 2017-11-15 11:55 UTC (permalink / raw)
  To: Alain.Cochard; +Cc: emacs-orgmode

Hello,

Alain.Cochard@unistra.fr writes:

> Thanks for pointing this out.  But boy is it complicated:

It is not. It follows regular isearch in Emacs. Quoting Emacs manual:

       An upper-case letter anywhere in the search string makes the search
    case-sensitive.  Thus, searching for ‘Foo’ does not find ‘foo’ or ‘FOO’.
    This applies to regular expression search as well as to literal string
    search.  The effect ceases if you delete the upper-case letter from the
    search string.  The variable ‘search-upper-case’ controls this: if it is
    non-‘nil’ (the default), an upper-case character in the search string
    make the search case-sensitive; setting it to ‘nil’ disables this effect
    of upper-case characters.

> But it does not seem to apply to multi-occur, which 'C-c a /' is said
> to use: both 'C-c a /' and 'M-x multi-occur' for 'FOO' only list
> 'FOO'...

Then it is an issues in Emacs, not in Org specifically. Indeed,
multi-occur's docstrings is

    Show all lines in buffers BUFS containing a match for REGEXP.
    This function acts on multiple buffers; otherwise, it is exactly like
    ‘occur’.

and occur's is

    If REGEXP contains upper case characters (excluding those preceded by ‘\’)
    and ‘search-upper-case’ is non-nil, the matching is case-sensitive.

> From my (user) point of view, I would expect that what is supposed to
> be a regexp behaves like a regexp, and in a consistent way for all
> cases (with 'C-c a s', when filtering with
> org-agenda-filter-by-regexp, etc.).

This is why `org-occur-case-fold-search' is a defcustom. If you set it
to nil, your search obeys to your regexp.

> PS: in the org-occur docstring:

[...]
>    The tree will show the lines where the regexp matches, and any
>    other context defined in `org-show-context-detail', which see.
>
> the last sentence above looks grammatically/syntactically funny to me.

This is an Emacs idiom. You find it here and there in its manual and
some docstrings. See
<https://lists.gnu.org/archive/html/bug-gnu-emacs/2017-10/msg00518.html>
for a related discussion in another package.

Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-15 11:55                           ` Nicolas Goaziou
@ 2017-11-15 12:35                             ` Alain.Cochard
  0 siblings, 0 replies; 27+ messages in thread
From: Alain.Cochard @ 2017-11-15 12:35 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard

Nicolas Goaziou writes on Wed 15 Nov 2017 12:55:

 > Alain.Cochard@unistra.fr writes:
 > 
 > > Thanks for pointing this out.  But boy is it complicated:
 
 > It is not. [...]

It still is for me, but your explanations do clarify things a bit.

Thanks for your time.


-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-14 20:55                         ` Tim Cross
@ 2017-11-15 14:02                           ` Nicolas Goaziou
  2017-11-15 21:14                             ` Tim Cross
  2017-11-16 10:05                             ` Alain.Cochard
  0 siblings, 2 replies; 27+ messages in thread
From: Nicolas Goaziou @ 2017-11-15 14:02 UTC (permalink / raw)
  To: Tim Cross; +Cc: emacs-orgmode, Alain.Cochard

Hello,

Tim Cross <theophilusx@gmail.com> writes:

> my 2 cents would vote for a variable which manages case folding. This
> would be in-line with how isearch works and something familiar to most
> Emacs users. I also prefer a single function which behaves differently
> depending on a config variable setting over separate functions as I
> think it makes key binding easier (though admittedly, it is trivial to
> define a lambda which selects between different functions depending on
> the setting of a config variable or prefix arg etc ).

Thinking about it, we may simply drop `org-occur-case-fold-search' and
use `search-upper-case' wherever that makes sense.

So far, "wherever that makes sense" includes:
- `org-occur'
- `org-search-view'
- what else?

WDYT?

Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-15 14:02                           ` Nicolas Goaziou
@ 2017-11-15 21:14                             ` Tim Cross
  2017-11-16 10:05                             ` Alain.Cochard
  1 sibling, 0 replies; 27+ messages in thread
From: Tim Cross @ 2017-11-15 21:14 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Alain.Cochard


Yes, that seems like a reasonable and consistent approach to me and most
likely to keep consistency across org-* and core emacs search functions.

regards,

Tim



Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Tim Cross <theophilusx@gmail.com> writes:
>
>> my 2 cents would vote for a variable which manages case folding. This
>> would be in-line with how isearch works and something familiar to most
>> Emacs users. I also prefer a single function which behaves differently
>> depending on a config variable setting over separate functions as I
>> think it makes key binding easier (though admittedly, it is trivial to
>> define a lambda which selects between different functions depending on
>> the setting of a config variable or prefix arg etc ).
>
> Thinking about it, we may simply drop `org-occur-case-fold-search' and
> use `search-upper-case' wherever that makes sense.
>
> So far, "wherever that makes sense" includes:
> - `org-occur'
> - `org-search-view'
> - what else?
>
> WDYT?
>
> Regards,


-- 
Tim Cross

^ permalink raw reply	[flat|nested] 27+ messages in thread

* Re: How to use case sensitive org-search-view?
  2017-11-15 14:02                           ` Nicolas Goaziou
  2017-11-15 21:14                             ` Tim Cross
@ 2017-11-16 10:05                             ` Alain.Cochard
  1 sibling, 0 replies; 27+ messages in thread
From: Alain.Cochard @ 2017-11-16 10:05 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: Tim Cross, emacs-orgmode, Alain.Cochard

Nicolas Goaziou writes on Wed 15 Nov 2017 15:02:

 > Thinking about it, we may simply drop `org-occur-case-fold-search' and
 > use `search-upper-case' wherever that makes sense.
 > 
 > So far, "wherever that makes sense" includes:
 > - `org-occur'
 > - `org-search-view'
 > - what else?

I take it that when, in search view, one uses `{' or `}' to add a new
regexp, it is part of `org-search-view'.

I wonder if this is also the case for `=' in other agenda views in
order to "Filter the agenda view by a regular expression"
(`org-agenda-filter-by-regexp').

And for `org-tags-view' for which "Each element in the search is
either a tag, a regular expression matching tags...", as well as
`org-agenda-bulk-mark-regexp' which marks "entries matching a regular
expression for bulk action".

Regards,
a.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     

^ permalink raw reply	[flat|nested] 27+ messages in thread

end of thread, other threads:[~2017-11-16 10:08 UTC | newest]

Thread overview: 27+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-09-18 14:04 Confused about the explanation for 'org-cycle' Alain.Cochard
2017-09-19  5:08 ` Matt Lundin
2017-09-20 10:57   ` Nicolas Goaziou
2017-09-26  8:54     ` Alain.Cochard
2017-09-26 10:41       ` Nicolas Goaziou
2017-09-26 12:48         ` Alain.Cochard
2017-09-28 13:44           ` org-list-empty-line-terminates-plain-lists removed but still mentioned in the manual Alain.Cochard
2017-09-28 14:07             ` Nicolas Goaziou
2017-09-28 14:31           ` Confused about the explanation for 'org-cycle' Nicolas Goaziou
2017-09-28 15:29             ` Robert Horn
2017-09-28 16:10               ` Kyle Meyer
2017-09-28 16:17                 ` Eric S Fraga
2017-09-28 21:04             ` Alain.Cochard
2017-09-28 21:22               ` Josiah Schwab
2017-09-28 21:30               ` Nicolas Goaziou
2017-10-05  8:17                 ` Alain.Cochard
2017-11-10 17:23                   ` How to use case sensitive org-search-view? Alain.Cochard
2017-11-14 14:26                     ` Matt Lundin
2017-11-14 15:30                       ` Alain.Cochard
2017-11-14 20:35                       ` Nicolas Goaziou
2017-11-14 20:55                         ` Tim Cross
2017-11-15 14:02                           ` Nicolas Goaziou
2017-11-15 21:14                             ` Tim Cross
2017-11-16 10:05                             ` Alain.Cochard
2017-11-15 10:49                         ` Alain.Cochard
2017-11-15 11:55                           ` Nicolas Goaziou
2017-11-15 12:35                             ` Alain.Cochard

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.