Warning: this is an htmlized version!
The original is across this link,
and the conversion rules are here.
(Re)generate: (find-anchors-intro)
Source code:  (find-eev "eev-intro.el" "find-anchors-intro")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



Introduction: `ee-anchor-format' and `to'
=========================================
A hyperlink like

  (to "foo")

jumps to the first occurrence of the string "«foo»" in the
current buffer. The way to convert from "foo" to "«foo»" is
controlled by the variable `ee-anchor-format', and the sexp
`(to "foo")' is roughly equivalent the third sexp below:

                            ee-anchor-format
                    (format ee-anchor-format "foo")
  (ee-goto-position (format ee-anchor-format "foo"))

We will call strings in `«»'s _anchors_, and we will say
that `(to "foo")' jumps "to the anchor `foo'".

Anchors can be used to create sections and indexes, as we shall
see soon - but due to some old design decisions that I was never
able to find good alternatives for, this tutorial needs to start
with a BIG WARNING.



WARNING: some glyphs need raw-text-unix
=======================================
The best way to make anchors stand out is to use colored glyphs
for them - just like we made `^O's appear as red star glyphs for
eepitch, as described here:

  (find-eepitch-intro "\nRed stars\n")

For historical reasons, the glyphs for `«' and `»' defined in

  (find-eev "eev-anchors.el")

use the characters 171 and 187; as far as I know, these
characters are only "safe" - in the sense that Emacs will not
try to convert them to anything else - in unibyte buffers. The
best way to make sure that anchors with `«»'s will work in a
certain file is to put a "Local variables:" section at the end
of it, as has been done in this buffer - and use that to set both
the file coding to raw-text-unix and the value of
`ee-anchor-format' to "«%s»".

Note that if you change a "Local variables:" section by hand
you will probably have to either reload the file or run `M-x
normal-mode' to make the new settings take effect.



Indexes
=======
In a situation like this,

  «one»   (to "two")
  «two»   (to "one")

we have two anchors, and typing `M-e' at the line with the anchor
"one" takes us to the line with the anchor "two", and typing
`M-e' at the line with the anchor "two" takes us to the line
with the anchor "one". In a situation like this we say that the
anchors "one" and "two" _point to one another_.

In a case like this,

  «.three»   (to "three")
   «three»  (to ".three")

where the names of two anchors pointing to one another differ by
an initial dot, we will say that the anchor ".three" is the
"index anchor", and the anchor "three" is the "section
anchor"; and one way to create an index for a file is to group
all the index anchors together. For an example, see:

  (find-eev "eev-intro.el" ".find-eev-intro")




Creating index/section anchor pairs
===================================
Use `M-A' (`eewrap-anchor'). Note that this has been briefly
mentioned here:

  (find-wrap-intro "All wrapping functions")

It will convert a line with a syntax like

  comment-prefix <anchor-name>

into:

  comment-prefix «.anchor-name»	(to "anchor-name")
  comment-prefix «anchor-name» (to ".anchor-name")

where comment-prefix is any string and anchor-name is a string
without `<>'s. Note that the `<>'s, which are easy to type, are
converted into `«»'s, which are harder.



find-anchor
===========
(find-eev "eev-anchors.el")
(find-eev "eev-anchors.el" "find-anchor")


code-c-d and :anchor
====================
(find-eev "eev-code.el" "ee-code-c-d-:anchor")



# Local Variables:
# coding:           raw-text-unix
# ee-anchor-format: "«%s»"
# End: