* [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
@ 2023-07-17 20:34 Jens Schmidt
2023-07-18 8:13 ` Ihor Radchenko
0 siblings, 1 reply; 10+ messages in thread
From: Jens Schmidt @ 2023-07-17 20:34 UTC (permalink / raw)
To: emacs-orgmode
[emacs-29]$ ./src/emacs -Q -L ~jschmidt/work/org-mode/lisp/
(org-version nil t)
"Org mode version 9.7-pre (release_9.6.7-562-g5b6268 @
/home/jschmidt/work/org-mode/lisp/)"
(setq org-hide-emphasis-markers t)
t
;; assume test.org being absent in cwd
C-x 4 f ;; find-file-other-window
t ;; self-insert-command
e ;; self-insert-command
s ;; self-insert-command
t ;; self-insert-command
. ;; self-insert-command
o ;; self-insert-command
r ;; self-insert-command
g ;; self-insert-command
<return> ;; minibuffer-complete-and-exit
* ;; org-self-insert-command
SPC ;; org-self-insert-command
t ;; org-self-insert-command
e ;; org-self-insert-command
s ;; org-self-insert-command
t ;; org-self-insert-command
C-c C-q ;; org-set-tags-command
t ;; self-insert-command
e ;; self-insert-command
s ;; self-insert-command
t ;; self-insert-command
<return> ;; exit-minibuffer
SPC ;; org-self-insert-command
= ;; org-self-insert-command
t ;; org-self-insert-command
e ;; org-self-insert-command
s ;; org-self-insert-command
t ;; org-self-insert-command
= ;; org-self-insert-command
SPC ;; org-self-insert-command
The final SPC after the closing equal sign lets point jump to before the
colon of the ":test:" tag.
Most likely, this is not limited to space, but that is just the
character I most frequently type after closing emphasis.
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
2023-07-17 20:34 [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)] Jens Schmidt
@ 2023-07-18 8:13 ` Ihor Radchenko
2023-07-18 19:55 ` Farblos
` (2 more replies)
0 siblings, 3 replies; 10+ messages in thread
From: Ihor Radchenko @ 2023-07-18 8:13 UTC (permalink / raw)
To: Jens Schmidt; +Cc: emacs-orgmode
Jens Schmidt <jschmidt4gnu@vodafonemail.de> writes:
> [emacs-29]$ ./src/emacs -Q -L ~jschmidt/work/org-mode/lisp/
>
> (org-version nil t)
> "Org mode version 9.7-pre (release_9.6.7-562-g5b6268 @
> /home/jschmidt/work/org-mode/lisp/)"
>
> (setq org-hide-emphasis-markers t)
> t
>
> ...
> The final SPC after the closing equal sign lets point jump to before the
> colon of the ":test:" tag.
Confirmed.
> Most likely, this is not limited to space, but that is just the
> character I most frequently type after closing emphasis.
No, it is space. In particular, it is `org--align-tags-here' + some bug
in Emacs that screws up column computation.
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64696
Fixed, on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=3e3b873d3
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
2023-07-18 8:13 ` Ihor Radchenko
@ 2023-07-18 19:55 ` Farblos
2023-07-18 20:53 ` Jens Schmidt
2023-07-20 20:55 ` Jens Schmidt
2 siblings, 0 replies; 10+ messages in thread
From: Farblos @ 2023-07-18 19:55 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
On 2023-07-18 10:13, Ihor Radchenko wrote:
> Confirmed.
Thanks for caring about this so quickly ...
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64696
... and for the discussion with Eli & co. Which I did not try to follow
TBH.
> Fixed, on main.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=3e3b873d3
Well, I have one not-so-minor nit here: With that commit you cannot
insert text *before* some text having hidden emphasis without breaking
the emphasis. More concretely (in an empty org-mode buffer):
t ;; org-self-insert-command
e ;; org-self-insert-command
s ;; org-self-insert-command
t ;; org-self-insert-command
SPC ;; org-self-insert-command
= ;; org-self-insert-command
t ;; org-self-insert-command
e ;; org-self-insert-command
s ;; org-self-insert-command
t ;; org-self-insert-command
= ;; org-self-insert-command
SPC ;; org-self-insert-command
t ;; org-self-insert-command
e ;; org-self-insert-command
s ;; org-self-insert-command
t ;; org-self-insert-command
C-<left> ;; left-word
C-<left> ;; left-word
SPC ;; org-self-insert-command
The last SPC breaks the emphasis around the middle "test", which it did
not previously. Previously, the SPC would just move the whole
emphasized word one space to the right. Which I somehow got used to,
and probably many others as well.
OTOH, to fix my bug, only the first of the new `org-rear-nonsticky-at'
calls is actually needed. So probably we could have something like the
following to get my bug fixed without any changes in behavior (diff on
top of main, that is, in addition to your commit):
diff --git a/lisp/org.el b/lisp/org.el
index 0d8b5386c..71f482f64 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -5153,8 +5153,7 @@ stacked delimiters is N. Escaping delimiters is
not possible."
;;
https://orgmode.org/list/8b691a7f-6b62-d573-e5a8-80fac3dc9bc6@vodafonemail.de
(org-rear-nonsticky-at (match-beginning 5))
(add-text-properties (match-beginning 3) (match-end 3)
- '(invisible t))
- (org-rear-nonsticky-at (match-end 3)))
+ '(invisible t)))
(throw :exit t))))))))
(defun org-emphasize (&optional char)
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
2023-07-18 8:13 ` Ihor Radchenko
2023-07-18 19:55 ` Farblos
@ 2023-07-18 20:53 ` Jens Schmidt
2023-07-19 4:35 ` Ihor Radchenko
2023-07-20 20:55 ` Jens Schmidt
2 siblings, 1 reply; 10+ messages in thread
From: Jens Schmidt @ 2023-07-18 20:53 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
[Resent with correct identity to make this visible on the list as well -
sorry for the hassle.]
On 2023-07-18 10:13, Ihor Radchenko wrote:
> Confirmed.
Thanks for caring about this so quickly ...
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64696
... and for the discussion with Eli & co. Which I did not try to follow
TBH.
> Fixed, on main.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=3e3b873d3
Well, I have one not-so-minor nit here: With that commit you cannot
insert text *before* some text having hidden emphasis without breaking
the emphasis. More concretely (in an empty org-mode buffer):
t ;; org-self-insert-command
e ;; org-self-insert-command
s ;; org-self-insert-command
t ;; org-self-insert-command
SPC ;; org-self-insert-command
= ;; org-self-insert-command
t ;; org-self-insert-command
e ;; org-self-insert-command
s ;; org-self-insert-command
t ;; org-self-insert-command
= ;; org-self-insert-command
SPC ;; org-self-insert-command
t ;; org-self-insert-command
e ;; org-self-insert-command
s ;; org-self-insert-command
t ;; org-self-insert-command
C-<left> ;; left-word
C-<left> ;; left-word
SPC ;; org-self-insert-command
The last SPC breaks the emphasis around the middle "test", which it did
not previously. Previously, the SPC would just move the whole
emphasized word one space to the right. Which I somehow got used to,
and probably many others as well.
OTOH, to fix my bug, only the first of the new `org-rear-nonsticky-at'
calls is actually needed. So probably we could have something like the
following to get my bug fixed without any changes in behavior (diff on
top of main, that is, in addition to your commit):
diff --git a/lisp/org.el b/lisp/org.el
index 0d8b5386c..71f482f64 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -5153,8 +5153,7 @@ stacked delimiters is N. Escaping delimiters is
not possible."
;;
https://orgmode.org/list/8b691a7f-6b62-d573-e5a8-80fac3dc9bc6@vodafonemail.de
(org-rear-nonsticky-at (match-beginning 5))
(add-text-properties (match-beginning 3) (match-end 3)
- '(invisible t))
- (org-rear-nonsticky-at (match-end 3)))
+ '(invisible t)))
(throw :exit t))))))))
(defun org-emphasize (&optional char)
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
2023-07-18 20:53 ` Jens Schmidt
@ 2023-07-19 4:35 ` Ihor Radchenko
2023-07-19 6:53 ` [BUG] Emphasis markers should be considered word constituents (was: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]) Ihor Radchenko
2023-07-19 7:10 ` [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)] Ihor Radchenko
0 siblings, 2 replies; 10+ messages in thread
From: Ihor Radchenko @ 2023-07-19 4:35 UTC (permalink / raw)
To: Jens Schmidt; +Cc: emacs-orgmode
Jens Schmidt <jschmidt4gnu@vodafonemail.de> writes:
>> Fixed, on main.
>> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=3e3b873d3
>
> Well, I have one not-so-minor nit here: With that commit you cannot
> insert text *before* some text having hidden emphasis without breaking
> the emphasis. More concretely (in an empty org-mode buffer):
>
> ...
> C-<left> ;; left-word
> C-<left> ;; left-word
> SPC ;; org-self-insert-command
>
> The last SPC breaks the emphasis around the middle "test", which it did
> not previously. Previously, the SPC would just move the whole
> emphasized word one space to the right. Which I somehow got used to,
> and probably many others as well.
OMG. What we had in the past is because of an obscure internal,
undocumented implementation detail of how Emacs adjusts point when it
ends up inside invisible region:
/* If the preceding character is both intangible and invisible,
and the invisible property is `rear-sticky', perturb it so
that the search starts one character earlier -- this ensures
that point can never move to the end of an invisible/
intangible/rear-sticky region. */
Except that we do not have intanglible property there and the code below
that comment does not always check for intanglible property.
> OTOH, to fix my bug, only the first of the new `org-rear-nonsticky-at'
> calls is actually needed. So probably we could have something like the
> following to get my bug fixed without any changes in behavior (diff on
> top of main, that is, in addition to your commit):
I am not sure if it is a proper fix. The basic problem is that Org's
syntax table does not declare emphasis markup as part of a word.
I need to consult Emacs devs about rules of point adjustment.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 10+ messages in thread
* [BUG] Emphasis markers should be considered word constituents (was: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)])
2023-07-19 4:35 ` Ihor Radchenko
@ 2023-07-19 6:53 ` Ihor Radchenko
2023-07-19 7:10 ` [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)] Ihor Radchenko
1 sibling, 0 replies; 10+ messages in thread
From: Ihor Radchenko @ 2023-07-19 6:53 UTC (permalink / raw)
To: Jens Schmidt; +Cc: emacs-orgmode
> Jens Schmidt <jschmidt4gnu@vodafonemail.de> writes:
> ...
>> Well, I have one not-so-minor nit here: With that commit you cannot
>> insert text *before* some text having hidden emphasis without breaking
>> the emphasis. More concretely (in an empty org-mode buffer):
>>
(setq org-hide-emphasis-markers t)
*foo*<point>
>> ...
>> C-<left> ;; left-word
>> SPC ;; org-self-insert-command
>>
>> The last SPC breaks the emphasis around the middle "test", which it did
>> not previously. Previously, the SPC would just move the whole
>> emphasized word one space to the right. Which I somehow got used to,
>> and probably many others as well.
The root cause revealed by my change is that Org mode does not always
consider emphasis markers to be word boundaries.
Note how when you do not hide emphasis markers, C-<left> will end up in
*<point>foo*
When emphasis markers are not hidden, things were the same, except that
Emacs adjusted point right to sticky invisible text in the direction of
point movement, leading to inconsistent behaviour between hiding and not
hiding emphasis markers.
Yet, Org sometimes does treat emphasis markers as word constituents:
At least, `org-fill-element' and `org-transpose-words' temporarily turn
emphasis markers into parts of words.
The situation is clearly a bit chaotic.
One of the reasons why we have such a mess is because *_/~+ are not
always representing emphasis. Proper distinction between *_/~+ that are
and aren't part of actual emphasis would require a custom
`syntax-propertize-function' that would query Org element API to
determine the context.
Unfortunately, using `syntax-propertize-function' it is not very
practical yet.
We need parser context down to object level, while we only cache parser
state down to element (paragraph) level. So, querying element API in
this case will lead to significant performance degradation, with
quadratic (N_objects_in_paragraph^2) complexity in some cases.
I will leave this bug report open until we have a better caching and can
reasonably implement custom `syntax-propertize-function'.
Or, if any, please post arguments against making emphasis markers word
constituents.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
2023-07-19 4:35 ` Ihor Radchenko
2023-07-19 6:53 ` [BUG] Emphasis markers should be considered word constituents (was: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]) Ihor Radchenko
@ 2023-07-19 7:10 ` Ihor Radchenko
2023-07-19 22:37 ` Jens Schmidt
1 sibling, 1 reply; 10+ messages in thread
From: Ihor Radchenko @ 2023-07-19 7:10 UTC (permalink / raw)
To: Jens Schmidt; +Cc: emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
>> OTOH, to fix my bug, only the first of the new `org-rear-nonsticky-at'
>> calls is actually needed. So probably we could have something like the
>> following to get my bug fixed without any changes in behavior (diff on
>> top of main, that is, in addition to your commit):
>
> I am not sure if it is a proper fix. The basic problem is that Org's
> syntax table does not declare emphasis markup as part of a word.
>
> I need to consult Emacs devs about rules of point adjustment.
I see no good way to address this quickly, so I re-added stickiness to
the opening emphasis marker, as you suggested.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=724135dda
Follow-ups:
1. https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64724 (for Emacs point
adjustment rules)
2. https://orgmode.org/list/87edl41jf0.fsf@localhost (for proper
handling of emphasis markers when moving across words)
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
2023-07-19 7:10 ` [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)] Ihor Radchenko
@ 2023-07-19 22:37 ` Jens Schmidt
0 siblings, 0 replies; 10+ messages in thread
From: Jens Schmidt @ 2023-07-19 22:37 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
On 2023-07-19 09:10, Ihor Radchenko wrote:
> I see no good way to address this quickly, so I re-added stickiness to
> the opening emphasis marker, as you suggested.
>
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=724135dda
>
> Follow-ups:
> 1. https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64724 (for Emacs point
> adjustment rules)
> 2. https://orgmode.org/list/87edl41jf0.fsf@localhost (for proper
> handling of emphasis markers when moving across words)
Thanks.
What a wasps' nest.
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
2023-07-18 8:13 ` Ihor Radchenko
2023-07-18 19:55 ` Farblos
2023-07-18 20:53 ` Jens Schmidt
@ 2023-07-20 20:55 ` Jens Schmidt
2023-07-21 8:30 ` Ihor Radchenko
2 siblings, 1 reply; 10+ messages in thread
From: Jens Schmidt @ 2023-07-20 20:55 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
On 2023-07-18 10:13, Ihor Radchenko wrote:
> No, it is space. In particular, it is `org--align-tags-here' + some bug
> in Emacs that screws up column computation.
>
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64696
FWIW the third test yields
■ Warning (emacs): Test #3:: ’word’ is hidden applying ’invisible
text property to heading body.
■ Warning (emacs): Moved point after first ’word’
■ Warning (emacs): 1:: current-column = 0
■ Warning (emacs): redisplayed
■ Warning (emacs): 2:: current-column = 0
■ Warning (emacs): Indented to column 50
■ Warning (emacs): 3:: current-column = 0
■ Warning (emacs): redisplayed
■ Warning (emacs): 4:: current-column = 0
■ Warning (emacs): Enabled visible mode
■ Warning (emacs): 5:: current-column = 50
■ Warning (emacs): redisplayed
■ Warning (emacs): 6:: current-column = 50
on my system which seems to be different from what you described.
And for the fun of it: With (indent-tabs-mode -1) tests 3 and 4 report
column 54 for "5::" and "6::".
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]
2023-07-20 20:55 ` Jens Schmidt
@ 2023-07-21 8:30 ` Ihor Radchenko
0 siblings, 0 replies; 10+ messages in thread
From: Ihor Radchenko @ 2023-07-21 8:30 UTC (permalink / raw)
To: Jens Schmidt; +Cc: emacs-orgmode
Jens Schmidt <jschmidt4gnu@vodafonemail.de> writes:
> On 2023-07-18 10:13, Ihor Radchenko wrote:
>
>> No, it is space. In particular, it is `org--align-tags-here' + some bug
>> in Emacs that screws up column computation.
>>
>> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64696
>
> FWIW the third test yields
>
> ■ Warning (emacs): Test #3:: ’word’ is hidden applying ’invisible
> text property to heading body.
> ■ Warning (emacs): Moved point after first ’word’
> ■ Warning (emacs): 1:: current-column = 0
> ■ Warning (emacs): redisplayed
> ■ Warning (emacs): 2:: current-column = 0
> ■ Warning (emacs): Indented to column 50
> ■ Warning (emacs): 3:: current-column = 0
> ■ Warning (emacs): redisplayed
> ■ Warning (emacs): 4:: current-column = 0
> ■ Warning (emacs): Enabled visible mode
> ■ Warning (emacs): 5:: current-column = 50
> ■ Warning (emacs): redisplayed
> ■ Warning (emacs): 6:: current-column = 50
>
> on my system which seems to be different from what you described.
I think it is same.
> And for the fun of it: With (indent-tabs-mode -1) tests 3 and 4 report
> column 54 for "5::" and "6::".
Interesting.
Same for me.
I will update the bug report.
P.S. You can reply to the bug report directly by sending email to
64696@debbugs.gnu.org
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2023-07-21 8:31 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-07-17 20:34 [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)] Jens Schmidt
2023-07-18 8:13 ` Ihor Radchenko
2023-07-18 19:55 ` Farblos
2023-07-18 20:53 ` Jens Schmidt
2023-07-19 4:35 ` Ihor Radchenko
2023-07-19 6:53 ` [BUG] Emphasis markers should be considered word constituents (was: [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)]) Ihor Radchenko
2023-07-19 7:10 ` [BUG] SPACE jumps to tag in header line after hidden emphasis marker [9.7-pre (release_9.6.7-562-g5b6268 @ /home/jschmidt/work/org-mode/lisp/)] Ihor Radchenko
2023-07-19 22:37 ` Jens Schmidt
2023-07-20 20:55 ` Jens Schmidt
2023-07-21 8:30 ` Ihor Radchenko
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.