(Re)generate: (find-anchors-intro)
Source code:  (find-eev "eev-intro.el" "find-anchors-intro")
More intros:  (find-eev-quick-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



Note: this intro needs to be rewritten!
Ideally it should _complement_ the material in:
  (find-eev-quick-intro "8. Anchors")



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")