Xref

Xref is a way of making Emacs more like a hypertext system, requiring no special formats for the files you link and no special knowledge to use.

Note that it has no connection with Info! The ways you follow links in this manual are different to the ones used by Xref.

This is version `$Id: xref.texi,v 1.2 2002/08/26 18:09:39 pws Exp $' of the Xref manual, which refers to Xref version 2.29.

Introduction		What Xref is and why you need it.
2. Preliminaries		How to get Xref up and running.
3. Basic ideas		Definitions and simple operations.
4. A lightning tour of Xref		An ultrashort guide to the most important commands.
5. A less brief introduction to Xref commands		A fuller introduction to commands.
6. Saving cross-references		How Xref can write out your cross-references.
7. Options		Advanced ways of customising Xref.

Appendices:

A. The Xref-bmk bookmarking package		A package to use Xref for bookmarks in your files.
B. Summary of command names and bindings		A list of command names and bindings.
C. Cutting and pasting cross-refs.		What happens when you move or copy a link.
D. Formats of saved cross-refs.		The two formats in which cross-refs. are saved.
E. Some tips on using Xref		The results of some experience with Xref.
F. Bugs		Erm...
G. Things to do		Possible enhancements.
Joke		Humour (not very much, though).

Indexes (for an index of commands, see the appendix @ref{Command summary}):

Concept index		General index.
Variable index		Index of all Xref variables mentioned.

--- The Detailed Node Listing ---

Introduction:

1.0 Possible uses for Xref		More blurb; skip this if you're already convinced.
1.1 Things that Xref is not designed for		What Xref is not; why you might want something else.
1.2 How to submit feedback about Xref		How to let me know about a bug.
1.3 Acknowledgements		People and packages that helped me write Xref.

Preliminaries:

2.1 Requirements for running Xref		What you need to be able to use Xref.
2.2 Acquiring the Xref package		How to get hold of a copy of the package.
2.3 How to set up Xref on your system		How to make it work for you.

Xref commands:

5.1 Conventions for keys and commands
5.2 Making, moving and deleting sources and their targets		Commands to set up and delete sources and targets.
5.3 Commands to move between sources and targets		Commands which move from source to source, or from source to target.
5.4 Going back to previous links and points		Commands to return to previous links and points.
5.5 Commands which toggle options on and off		Commands which change Xref's behaviour.
5.6 Selecting commands from a menu
5.7 Miscellaneous commands (searching, inserting, status)		Searching, inserting, deleting, status.
5.8 Xref commands in restricted buffers		A note on how Xref deals with narrowed buffers.

Making a link:

5.2.1 Defining and moving sources		How to make a new source or move an old one.
5.2.2 Defining and moving targets		How to make a new target or move an old one.
5.2.3 Making a link point at a whole file		How to make a simple target which points to a file.
5.2.4 Defining and editing action targets		Defining targets which do something.
5.2.5 Reusing existing targets		How to reuse an old target for a new source.
5.2.6 Deleting links and their sources or targets		How to delete a source, a target, or the link.

Moving around:

5.3.1 Going to an existing current cross-reference		When a current cross-ref. exists.
5.3.2 Using ordered lists of sources		Moving between sources in order.
5.3.3 Setting a new current cross-reference		Making a new cross-ref. current.
5.3.4 Following the nearest source to its target		Following the nearest source.
5.3.5 Following a cross-ref. with the mouse

Moving back:

5.4.1 Going back through followed links		Following a trail of links in reverse.
5.4.2 Going back where you were before an Xref command		Going back where you were before a command.

Toggling options:

5.5.1 Following cross-refs. automatically
5.5.2 Highlighting all targets of all cross-refs.		Making all targets highlighted.
5.5.3 Making all cross-refs. invisible
5.5.4 Putting Xref's keymap onto the main one		Putting Xref's map onto the main map.

The Xref menu:

5.6.1 Using Xref commands from the menu bar		Selecting Xref commands from the menu bar.
5.6.2 Using Xref commands with a mouse event		Bringing up the menu with the mouse.

Miscellaneous:

5.7.1 Searching for a source by regexp		Regular expression search for a source.
5.7.2 Unhighlighting the current link
5.7.3 Inserting or displaying the source		Copying/displaying the highlighted source text.
5.7.4 Status summary for the current buffer		Showing the status of links and options.

Restrictions:
(no subtopics)

Saving cross-refs.:

6.1 Saving cross-refs. in the visited file
6.2 Saving cross-refs. in another file
6.3 Controlling if, where and how Xref saves cross-refs.		Taking control over where cross-refs. are saved.
6.4 Brief summary of reading and saving cross-refs.		A brief summary of how Xref reads and saves things.

Controlling saves:

6.3.1 Saving different files in different places
6.3.2 Checking other files for cross-refs.
6.3.3 Making Xref ignore changeable text at the start		Making Xref ignore changeable text.
6.3.4 Preventing Xref from writing cross-refs.
6.3.5 Reminder: which variables are buffer-local		Reminder of what needs setq-default.

Options:

7.1 Options for tracking sources and targets		How to track sources and targets automatically.
7.2 Minor variables: highlighting, messages		Things you might want to set now and then.
7.3 Changing the appearance of sources and targets		How to change the way links look.
7.4 Circumventing woe with font-lock-mode

Appendix: Xref-bmk

A.1 How to install Xref-bmk		How to install the Xref-bmk package.
A.2 Basic use of Xref-bmk		How to make and use bookmarks with Xref-bmk.
A.3 More advanced usage of Xref-bmk		The bookmark file itself, plus some options.
A.4 Comparing `bookmark.el' with `xref-bmk.el'		Important differences between the packages.

Advanced Xref-bmk:

A.3.1 The file where bookmarks are saved		You can edit the file with the saved bookmarks.
A.3.2 Options controlling Xref-bmk		Options to set in Xref-bmk.

Appendix: Formats

D.1 Format of saved targets		Format of saved cross-ref. targets.
D.2 Format of saved sources		Format of saved cross-ref. sources.

Appendix: Tips:

E.1 Misaligned cross-refs.		Fixing cross-refs. which appear in the wrong place.
E.2 Transferring a file from DOS		Making sure carriage returns are removed.

Introduction

The Xref package for GNU Emacs is a simple but powerful way of adding cross-references or hypertext links to any file, even ones which aren't writable. The links appear highlighted under Emacs, but don't appear in the file text itself. It works a bit like following a cross-reference in Emacs' Info system, with two important exceptions: no special formatting is necessary for the file containing either sources or targets of the cross-references, and you can add or remove the sources, targets and the connections between them at any time without changing the underlying text. See section 3. Basic ideas, for definitions.

You can do everything with just a few keystrokes, though a full set of commands and options is available. In fact, you can mark links between any two points in any two files you can access just by knowing two new keystrokes. You can continue to edit the files as well; you can more or less forget about the links while you are doing so and they will be preserved. Linking to remote files via Ange-FTP is transparent as usual, but this is thanks to Ange-FTP, not Xref.

Currently, unlike Texinfo there are no facilities for making the cross-references appear in any printable format; they are only useful within Emacs.

This manual assumes some minimal knowledge of Emacs Lisp to set variables in your `~/.emacs' file. In fact, you can even avoid that if you don't want to change the way Xref is set up to save cross-refs., or any of its options.

1.0 Possible uses for Xref		More blurb; skip this if you're already convinced.
1.1 Things that Xref is not designed for		What Xref is not; why you might want something else.
1.2 How to submit feedback about Xref		How to let me know about a bug.
1.3 Acknowledgements		People and packages that helped me write Xref.

1.0 Possible uses for Xref

The possible uses are legion. You might want to link your Makefile to various pieces of source code; you might want to add easy-to-follow notes to your latest essay without disturbing the original; you might simply want to have something less fiddly than those endless "(see section V paragraph ii)" notes in your on-line documentation.

You can go up and down lists of sources, or backwards over the trail of links you followed, so you could forget about targets and use Xref simply to mark sections in a format-independent way. For this type of usage there are commands which complete the text of the starting points of cross-references.

1.1 Things that Xref is not designed for

Other hypertext packages exist: Hyperbole, for example, is a large and powerful one. Xref is specifically designed towards occasions when both sources and targets of links are in files which are liable to change and which are not specially formatted.

The formats and commands are chosen so that Emacs does all the hard work at every stage, defining as well as following cross-refs., while the file you are editing has the least possible interference. For this reason, Xref is unlike any standard hypertext language. As you would expect, the data structures are based around Emacs Lisp.

Also, the Xref package has no relationship with cxref, and currently has no facilities for turning cross-refs. into readable file text for browsing outside Emacs.

1.2 How to submit feedback about Xref

There is now a command xref-submit-bug-report for you to e-mail problems to me, providing your mailer talks to the Internet. This is the only user command not bound to a key in xref-map by default. I welcome any suggestions and comments as well as bug reports.

It's quite hard to tell to what uses Xref will be put, so I would be interested to hear reports on people's patterns of usage: what functions or options they find particularly and others they would never use. This might help me keep the size of the package within reasonable limits.

1.3 Acknowledgements

The current version, using text properties, came about thanks to suggestions from Richard Stallman. Xref would never have been written without Darryl Okahata's and others' work on Oemacs which meant I could write it at home. I have lifted chunks of code from `simple.el', `files.el' and `etags.el'. Karl Fogel's bookmark mode also made me think about things I could do and helped me with the X menu commands. I also pinched some X ideas from w3.

2. Preliminaries

2.1 Requirements for running Xref		What you need to be able to use Xref.
2.2 Acquiring the Xref package		How to get hold of a copy of the package.
2.3 How to set up Xref on your system		How to make it work for you.

2.1 Requirements for running Xref

For the full facilities, GNU Emacs 19 with a windowing system is required. Emacs 19 changed a lot over its early versions, so you should ensure you have a recent version. At the time of writing the current version was 19.25.

Xref will now work on dumb terminals, but you will not see the cross-references highlighted. However, this should be the only difference; if you see extra error messages this is a bug and should be reported. You should still load it so that links can be updated properly; this should be entirely transparent to you. If you used version 1 you will probably need to change the initialisation commands to arrange this.

Under DOS, Oemacs with direct screen writes (the default) should be used. In this case, all the facilities are available and there should be no extra problems -- in fact, the package was written using Oemacs. There is a minor exception in that the fix for an old bug with redisplaying text when the fonts changed has not propagated through to Oemacs yet, but will do. I have no information regarding Oemacs running under DV/X, though it should pose no problem.

Xref now supports XEmacs, formerly known as Lucid Emacs (don't confuse this with older versions of Emacs which used the name `xemacs' just to indicate they supported X-Windows). The version uses the `text-prop.el' compatibility package rather than XEmacs' own `extents' feature, which would be preferable. It is very unlikely I will convert the package to use extents myself, however; also, it would not then be sensible to use the same version for both XEmacs and FSF Emacs. Any major differences between XEmacs and FSF versions are bugs, though minor differences are inevitable, particularly in the behaviour of and code for using the mouse.

2.2 Acquiring the Xref package

Currently Xref is available on the web at `http://www.pwstephenson.fsnet.co.uk/computing/'. There are four files:

`xref.el'

The main package.

`xref-hks.el'

A much smaller package which can be loaded from your `.emacs' file or from `default.el' and which will load the main package when it notices cross-references which refer to a file you are visiting.

`xref-bmk.el'

A bookmarks package implemented using xref; it has advantages and disadvantages compared with the standard bookmark package. It is not described further in this guide.

`xref.tex'

The source for the documentation you are reading.

Eventually, the FSF may start to distribute Xref, so if your Emacs is later than 19.25 look and see if you already have it.

2.3 How to set up Xref on your system

The files `xref.el' and `xref-hks.el' should be somewhere in the directories listed in your load-path; the obvious place is in the site-lisp directory of the emacs hierarchy, if you have permission to put it there. Otherwise, put it in a directory such as `~/elisp' and add the following to your .emacs file:

(setq load-path (cons (expand-file-name "~/elisp") load-path))

You may want to byte-compile `xref.el' using M-x byte-compile-file; unless your are using a very fast computer this should improve the performance noticeably. You can ignore the various `not known to be defined' error messages and the `reference to free variable' message about comment-line-start.

You will need at the least to have the keys defined. All Xref keys are attached to a single prefix; I use f8 (function key 8) but C-c x would be a sensible alternative. You might even consider C-x x, since copy-to-register is duplicated on C-x r x. All Xref keyboard commands consist of this prefix followed by one more keystroke. Putting the following in your `.emacs' file will do the trick; delete any global-set-key lines you don't want(1):

(global-set-key [f8] 'xref-map) (global-set-key "\C-cx" 'xref-map)

You now have to arrange for old cross-references to be read in and activated each time you read a cross-referenced file. There is a separate and substantially smaller package, `xref-hks.el', which will arrange to read in `xref.el[c]' if it finds existing cross-refs. Put the following line in your `.emacs' file:

(require 'xref-hks)

In summary, simply loading `xref-hks' automatically and defining a key prefix should be all you need. If you don't load `xref-hks' you will need to autoload the main package:

(autoload 'xref-map "xref" "Cross-referencing package" t 'keymap)

and you will have to load Xref by hand before you edit a file containing cross-refs. If you plan to use Xref at all seriously, the xref-hks method is highly recommended.

When you have this all set up, try editing the file `xref.el'; don't worry if you don't have write access to it. Hit your prefix key, then a. You should be sitting on top of a highlighted this. You can test following the cross-reference as described there. Yes, they're just as easy to define as they are to use.

3. Basic ideas

A cross-ref. source is a region of a buffer which usually appears underlined; in Oemacs under DOS it appears with a green foreground. Many Xref commands will make a source current, in which case it appears highlighted. A source is usually linked to a target, a region in the same or some other buffer; following the source with an Xref command will take you to this point.

The target of the current source is highlighted; on a colour display it appears with the colours opposite to the current source. Usually (for clarity) targets do not show up unless they are current.

Instead of pointing to a file, a target may specify an action; such targets are associated directly with the source. Otherwise, targets exist independently of their sources and may be moved around without the source needing to be made `aware' that the target has moved. Xref tries to make sure the link from a source can find its target if the latter moves. This means that you can edit a file containing a target completely separately from the file(s) containing its source(s).

Note that a source does not need to have a target. No error is caused unless you explicitly try to go to the target of a source which has no target. This means that you can simply define sources and use them as permanent markers in your text, jumping from one to another with the j, n and p commands. On the other hand, a target without a source is not particularly useful, hence the only way to define a new target is as the target of the current source.

A source can only have one target, but a target may, in principle, have more than one source. To reuse a target in this fashion, you should use the command specially designed for that purpose: see 5.2.5 Reusing existing targets.

Sources and targets appearing in the same location -- in fact, overlapping in any way -- are now expected to work properly. In other words, it is now useful to have a target which is also the source of a new link. It is not possible to have two different sources or targets in the same place, though they can touch one another.

4. A lightning tour of Xref

Find a bit in some file you want to point to somewhere else. Put a region over it and type prefix r where prefix is the key prefix you defined in 2.3 How to set up Xref on your system. That's the source. Find the bit you want it to point to, put a region over it and type prefix C-r. That's the target. Move to the source and type prefix f, which follows the cross-ref. to the target. You can return through this link with prefix l. Save the files with prefix C-s: if the file was writable, the cross-refs. are now saved in all that garbage tacked on the end; if it wasn't, they're in a file called `.emacs-xrefs' in the same directory, if that was writable; if it wasn't, they're in `.emacs-xrefs' in your home directory. That's it.

5. A less brief introduction to Xref commands

From now on the prefix before the commands is to be understood; in other words, when instructed to type w you should first type the key prefix you defined in 2.3 How to set up Xref on your system, then w. Most commands are only referred to in this fashion, so to see the command name you will need to look at the appendix B. Summary of command names and bindings. This is because Xref is designed mainly to be driven by keystrokes. If you need to call functions non-interactively, use C-h k followed by the keystroke for more detailed information; that information is not generally duplicated here.

5.1 Conventions for keys and commands
5.2 Making, moving and deleting sources and their targets		Commands to set up and delete sources and targets.
5.3 Commands to move between sources and targets		Commands which move from source to source, or from source to target.
5.4 Going back to previous links and points		Commands to return to previous links and points.
5.5 Commands which toggle options on and off		Commands which change Xref's behaviour.
5.6 Selecting commands from a menu
5.7 Miscellaneous commands (searching, inserting, status)		Searching, inserting, deleting, status.
5.8 Xref commands in restricted buffers		A note on how Xref deals with narrowed buffers.

5.1 Conventions for keys and commands

There is one convention about the keys that you should note. Many commands dealing with sources have corresponding commands dealing with targets, for example xref-next-source and xref-next-target. In such cases the `source' command is bound to a key without CTL pressed, while the `target' command is bound to the same key with CTL held down: in this example, n and C-n.

To avoid confusion, you should also note that commands like xref-next-target (C-n), which contain the word `target', always reach the target by following some source. In this case, the `next' refers to the fact that Xref will look at the next source after the current one, and take you to the target of that. Likewise, xref-jump-target (C-j) takes you to the target whose source has the text you specify. In fact, there are no commands which refer to the order or text of targets. Any piece of text you want to refer to in that way should be a source.

5.2 Making, moving and deleting sources and their targets

5.2.1 Defining and moving sources		How to make a new source or move an old one.
5.2.2 Defining and moving targets		How to make a new target or move an old one.
5.2.3 Making a link point at a whole file		How to make a simple target which points to a file.
5.2.4 Defining and editing action targets		Defining targets which do something.
5.2.5 Reusing existing targets		How to reuse an old target for a new source.
5.2.6 Deleting links and their sources or targets		How to delete a source, a target, or the link.

5.2.1 Defining and moving sources

The commands w and r put a cross-ref. source on the nearest word or the region from point to mark, respectively. The source you set up will become current (highlighted instead of underlined) so that you can immediately define a target.

If you give either a prefix argument, usually by typing C-u before the Xref prefix, the existing current source is moved onto the specified word or region. This is useful if you put it in the wrong place to begin with. The new source can overlap with the one you are altering.

The definition of `word' used by the w command needs some explanation. In programming modes, any character which can appear in a symbol of the appropriate language is treated as part of a word, so a hyphen in Lisp is treated as part of a word. This seems more useful for defining links. In text modes a `word' will be what you expect.

When moving a source is the only time sources can overlap; otherwise, the later source will always take precedence and any older one will have its overlapping portion truncated, or even be obliterated entirely. However, sources can overlap with targets with no problem.

5.2.2 Defining and moving targets

C-w and C-r define a target on a word or region for the current source. You need to set a source first, either by the commands above, or by making an existing source current as described in the next section.

As with the corresponding source commands, a prefix argument before either of these commands will move the existing target of the current source to the word or region specified. You should be careful when doing this because any other sources which point at the same target will be affected. If you know there are no other such sources this is safe.

If the current source already has a target and you do not give C-w or C-r a prefix argument, the new target becomes the current target but the old one is left where it is. Of course, this leaves the fairly minor danger of cluttering up the file with unused targets.

Having done this, the source and its target will work (you can follow the link) with no further work on your part.

5.2.3 Making a link point at a whole file

Sometimes you don't need a cross-ref. to lead to a particular place in a file, just the file itself. Sometimes, also, you may not want the hassle of maintaining the position of a full target in a file which you may not even own. For example, you may simply want to refer to a file in an FTP archive via Ange-FTP, without worrying about its contents.

In this case you can define a target by using SPC anywhere in the file which is to be the target. This file then becomes the target of the current source. Whenever you follow the cross-ref., you will be taken to the file, but point in that file will not be altered from what it was.

Giving a prefix argument to SPC will instead prompt you for the name of the file to be the target of the cross-ref. Completion is available, but the file whose name you typed does not have to exist.

5.2.4 Defining and editing action targets

There is also an `action' type target. After setting a source, you may use the @ command which prompts for a string, which specifies something Emacs is to do when you try to `follow' the link, or go to the target in some way. By default the string is an Emacs command; any Emacs-Lisp code is acceptable. If the string begins with `!', the rest of the string is passed to the shell as if it were a line for M-! (shell-command); if it begins with a `;' the rest of the string is simply displayed as a message at the bottom of the screen. As with M-!, you shouldn't type the quotes around the string.

If the current source already has an action-type target, you are presented with that for editing when you type @, so you can edit mistakes.

This feature was added for some compatibility with other hypertext packages and is not really a fundamental part of Xref, nor is it very sophisticated. I would appreciate feedback about it. It may be upgraded to something fancier in the future if that seems advisable.

5.2.5 Reusing existing targets

The C-x (for eXisting) command allows you to reuse a target, making it also the target of the current source. Simply place the cursor somewhere in the target you want to reuse and type the command. You may want to use h to highlight all targets in order to do this: see 5.5.2 Highlighting all targets of all cross-refs..

You can also place the cursor on a source (other than the current one, obviously); then Xref will use the target of that source as the target of the current one. This is the way to reuse targets which are actions.

5.2.6 Deleting links and their sources or targets

You can delete the current Xref with d. You can give the command a prefix argument, which tells it not to delete the target, just the source. This might be useful because Xref has no way of knowing in general whether the target is also the target of a different source.

As an alternative to deleting links one by one, the C-d command allows you much more control over deleting cross-refs., both sources and targets, not necessarily the current one. It prompts for a code, and requires at least two letters, though any combination of the valid codes may be given in any order.

One code specifies what the function is to delete. There are three possibilities:

`s'

delete any applicable sources

`t'

delete any applicable targets, and

`f'

follow the links of any applicable sources and delete the target found.

The other code specifies where the function is to look for things to delete. The four possibilities are:

`c'

look at the current cross-ref.: `t' and `f' are equivalent in this case as the current target is the same as the target of the current source,

`h'

look here: any source or target at point is applicable,

`b'

look through the current buffer; any source or target found is applicable, and

`r'

look through the region for sources and targets; this overrides the b option if both are given.

No error is signalled if no applicable source or target is found at any stage.

You can type `?' at any point after the `Enter options:' prompt for a summary of the available options.

There is one subtlety: you can actually specify none of `s', `t' or `f'. In this case, no sources or targets are deleted, but the links from any sources found will be broken. Since you can change the target of a source without explicitly breaking the link (see section 5.2.2 Defining and moving targets), you probably won't use this very often.

For example, if you copy a large chunk of text into a new file and want to make sure the buffer into which you are copying has no sources or targets, you would use the code `bst', which is the initial default. Note you would not use `bsf' in this case; some of the sources you copied might point back into the original buffer, for example, and the `f' would tell Xref to delete the target there, which is not what you want.

The code `cst' is equivalent to the d command and the code `cs' is equivalent to the d command with a prefix argument.

5.3 Commands to move between sources and targets

All the commands here respect the settings of the user options xref-track-sources (on by default) and xref-track-targets (off by default), see 7. Options. This means that, if you haven't changed the settings, making a new cross-ref. current source takes you direct to the beginning of its text unless the command explicitly takes you direct to the target.

The movement commands in the first two subsections below have the parallel source/target form.

5.3.1 Going to an existing current cross-reference		When a current cross-ref. exists.
5.3.2 Using ordered lists of sources		Moving between sources in order.
5.3.3 Setting a new current cross-reference		Making a new cross-ref. current.
5.3.4 Following the nearest source to its target		Following the nearest source.
5.3.5 Following a cross-ref. with the mouse

5.3.1 Going to an existing current cross-reference

g goes to the current source and C-g to its target. The o and C-o commands are similar but do so in another window. An error is signalled if there is no current cross-ref. Under XEmacs you probably can't use C-g, even after a prefix, so C-t is bound to the same command.

The g and C-g commands are called implicitly by any other command which takes you direct to a source or target. Whether called implicitly or explicitly, they both set a mark for use by the b command, and C-g adds a link to the list remembered for use by the l command (see section 5.4.1 Going back through followed links). C-g is by-passed when the target-tracking mechanism is used.

Whenever point is moved to a source or target, it is always to the first character.

5.3.2 Using ordered lists of sources

There are four pairs of commands dealing with sources in order. The keystrokes chosen parallel those for going to beginning and end of lines, and going up and down lines. Thus there are a (beginning), e (end), n (next), and p (previous). The n and p commands take you up and down the sources in whatever buffer the current source happens to be; the a and e commands take you to the the first/last source in the buffer you are currently editing. In other words, n and p are sensitive to the current Xref, while a and e are not; this should be what you expect.

The sources do not need to be in any particular structure; only the order of the text is important. The location and order of the targets is never significant, as explained in 5.1 Conventions for keys and commands. This means that C-a takes you to the target of the first source in the current buffer, wherever that target happens to be -- it could be the fourth target in a file residing somewhere on an FTP-accessible disk in Kalamazoo for all Xref cares; likewise C-e, C-n and C-p.

If there is no current cross-ref., n and p will behave like a and e respectively; likewise C-n and C-p will behave like C-a and C-e.

5.3.3 Setting a new current cross-reference

You can make the source nearest to the cursor current with c: this is the basic `context-sensitive' command, used by the commands for following links in the next section. If you give it a positive prefix argument, it will look for the next source after point; with a negative prefix argument it will search for the nearest source immediately before point. Contrast this with n and p in the previous subsection which refer to the source before or after the current one.

The j and C-j commands allow you to enter the text of a source then take you to that source or its target, respectively. Their major use is that they have completion of any applicable source text. The completion used is not strict, so you can still enter any text you like, but it must match a source exactly. Use s for a looser search with no completion: see 5.7.1 Searching for a source by regexp.

Normally the two commands search ahead from whatever source happens to be current (wherever that is, not necessarily the current buffer); with a prefix argument they will search the whole of the current buffer. This is quite useful if you have sources with identical text: typing j then RET on its own takes you to the next such.

5.3.4 Following the nearest source to its target

The c command described in the previous subsection is used by f, which follows the nearest cross-ref. source to point, and C-f, which does the same in another window. The prefix works the same way as with c: positive means only look after point, negative means only look before. In fact, f could more consistently be renamed C-c, but you don't necessarily associate following with making a current cross-ref.

These are the simplest commands to use if you want to follow cross-references without worrying about what is current.

5.3.5 Following a cross-ref. with the mouse

When you load Xref it will redefine mouse button 1 so that clicking on a cross-ref. source and then releasing the button will follow the cross-ref. to its target in the same window. However, if the mouse is not pointing at a source Xref will instead call the function originally mouse-1, usually mouse-set-point. Consequently, you should notice no change in the mouse behaviour unless it is pointing at a cross-ref. source. Of course, if there is a local binding for the mouse button the Xref function will not be available.

Mouse button 3, which should be the right-hand button on both 2- and 3-button mice, is similar except that the target is displayed in a window different from that where the source was clicked. It also retains its original function when clicked anywhere other than a source.

If you want to bind to another mouse event, you can use the function xref-bind-mouse, which works like global-set-key but with the bonuses explained above; for example

(xref-bind-mouse [mouse-2] 'xref-mouse-follow-xref) (xref-bind-mouse [C-mouse-2] 'xref-mouse-follow-xref-other-window)

In XEmacs, change [mouse-2] to 'button2 and [C-mouse-2] to '(control button2). Only these two functions have the effect of preserving the original command outside cross-ref. sources.

On the other hand, should you want to put mouse-1 or mouse-3 back to their original functions after Xref has rebound them, the lisp incantation is

(global-set-key [mouse-1] (symbol-function 'xref-other-mouse-1))

and similarly for mouse-3.

If you want to change only the non-Xref behaviour of the mouse buttons, just use global-set-key with the non-Xref function, then xref-bind-mouse to restore the Xref function.

Note that dragging with the mouse is not affected; that is why Emacs has to wait until you release the mouse key before following the cross-ref.

5.4 Going back to previous links and points

Xref remembers two sets of positions: firstly, a set of links you have followed; secondly, a set of points at which you were when you called an Xref command. Both of these are stored on rings, which means that if you call either of the commands enough times you will reach the beginning again.

5.4.1 Going back through followed links		Following a trail of links in reverse.
5.4.2 Going back where you were before an Xref command		Going back where you were before a command.

5.4.1 Going back through followed links

There is a command l (for last) which allows you to go back through a number of previous links. Every time you use it, a cross-ref. which you previously followed (not simply made current) is made current again. So if you followed a link from `file1' to `file2', then from `file2' to `file3', the l command will first take you back to file2, then the next time (assuming you don't follow any more cross-refs. from file2) back to file1. This assumes that the variable xref-track-sources is set, which is true by default (see section 7. Options). Note that links which were `followed' automatically, by displaying the target in another window which wasn't selected (see section 5.5.1 Following cross-refs. automatically) are not remembered for use by the l command.

The C-l command makes the previous link current in the same way as l but then takes you direct to the target. This is not quite like l as that doesn't necessarily take you to the source if xref-track-sources is not set. However, it does seem to be convenient.

If you need to store more links, increase the value of the variable xref-ring-max; the default is 32.

5.4.2 Going back where you were before an Xref command

You can also go back to the point you were at before an Xref command moved you by using b; this remembers points rather than cross-refs. It works even if you didn't follow the link, so after a takes you to a source, b will take you to where you were before. If your usage of Xref is like mine, however, you will probably find that the sequence of points remembered is somewhat unstructured. The l command described in the previous subsection is generally more useful.

However, you can store more points for use by the b command by increasing the value of the variable xref-mark-ring-max (default 16).

5.5 Commands which toggle options on and off

There are various commands which change the status of Xref. They are all toggles, so that hitting the key will alternately turn the feature on and then off. Supplying a non-zero numerical argument (or prefix) will ensure the feature is turned on while zero will turn it off; this is useful in your `.emacs' file.

5.5.1 Following cross-refs. automatically
5.5.2 Highlighting all targets of all cross-refs.		Making all targets highlighted.
5.5.3 Making all cross-refs. invisible
5.5.4 Putting Xref's keymap onto the main one		Putting Xref's map onto the main map.

5.5.1 Following cross-refs. automatically

t (standing for `track') is perhaps the most interesting toggle command. With this in effect, simply moving the cursor into a source will make it current and display the corresponding target in another window. See section 7. Options, for the discussion of the variables xref-minibuf-auto-track and xref-track-targets: the command works by setting xref-track-targets and making the source current whenever the cursor moves into a source region.

To turn this on in `.emacs', use

(xref-toggle-auto-track 1)

5.5.2 Highlighting all targets of all cross-refs.

Normally, only the target of the current cross-ref. is highlighted; the remaining targets are invisible. h highlights all targets, so you can see where they are.

If you need to turn this on in Lisp code, use

(xref-toggle-target-highlighting 1)

5.5.3 Making all cross-refs. invisible

v unhighlights all cross-ref. sources and targets, so that cross-refs. blend into the background.

To turn this on from Lisp code, use

(xref-toggle-invisible 1)

5.5.4 Putting Xref's keymap onto the main one

m binds the Xref keymap on top of the global one, so you just need to type one set of keys for each Xref command. This means that hitting m on its own (without the usual prefix) will turn this off. When this is in effect, `xref(m)' will appear in the modeline as if a minor mode were in effect. Unfortunately with a dumb terminal you lose the cursor keys; C-n etc. behave as xref-next-source, and so on, and in this case Emacs cannot tell the difference between C-n and the DOWN-key. There is no problem when using a windowing system as the cursor keys generate different events.

In Lisp code, you should probably use the function xref-toggle-xref-map with an explicit 1 or 0 argument.

5.6 Selecting commands from a menu

Xref has a menu which allows you to select commands by name rather than by remembering a keystroke. However, the commands in the menu are also labelled with the key to which they are usual bound in the main Xref keymap to remind you and to help you find the documentation.

Menu items labelled with keys are selectable; the titles are not. Most of the items call ordinary Xref commands, but under X Windows the special `Jump to source' and `Jump to target' items pop up a menu of all sources in the selected buffer from which you can select with the mouse.

For the `jump' commands, if the the selected window has no sources, Xref will try to find a buffer where there are sources: this will usual be the buffer of the current source, or last source to be current. This buffer is not necessarily visible.

There are two ways of using the menu; the first is easier.

5.6.1 Using Xref commands from the menu bar		Selecting Xref commands from the menu bar.
5.6.2 Using Xref commands with a mouse event		Bringing up the menu with the mouse.

5.6.1 Using Xref commands from the menu bar

If you are using X Windows and have not disabled the menu bar, then when Xref is loaded you will see an `Xref' item in inverse video at the top of the screen. Selecting this with the left hand mouse button produces a menu with some of the most useful Xref commands; releasing it on an item will perform that action. Where a point in some buffer is implied, it is the location of the cursor, not the mouse, which is used.

Some commands require there to be a current cross-ref.; if there is none, they will appear in a fuzzy font and you will not be able to select them.

5.6.2 Using Xref commands with a mouse event

The menu attached to the menu bar can also be bound to a mouse event; a down event is easiest as then the menu item will be selected when you release the mouse button. For example,

(global-set-key [C-S-down-mouse-1] 'xref-popup-menu)

in FSF Emacs. In XEmacs the down is redundant (and illegal) and the syntax is different:

(global-set-key '(control shift button1) 'xref-popup-menu)

(In XEmacs, xref-popup-menu is a different command; in FSF Emacs it is simply an alternative name for xref-menu-map.) Then holding CTL and SFT and pressing the left-hand mouse button will bring up the Xref menu. It is used exactly as described in the previous subsection.

There is one minor enhancement: since the mouse click is now in a particular buffer, the `Jump' items will pop up a list of sources in the buffer where you click, even if it is not selected, while the source or target will appear in the selected buffer. None of the other commands have been modified to be `mouse-aware' and consequently use point in the selected window where required. This does not work in XEmacs.

The menu is most useful with a mouse; you can bind it to an ordinary keypress via e.g. (global-set-key "\C-x\C-m" 'xref-menu-map), but you will probably find that tedious to use.

5.7 Miscellaneous commands (searching, inserting, status)

These commands don't obviously fit into any other section, but you may well need all of them at some time or another.

5.7.1 Searching for a source by regexp		Regular expression search for a source.
5.7.2 Unhighlighting the current link
5.7.3 Inserting or displaying the source		Copying/displaying the highlighted source text.
5.7.4 Status summary for the current buffer		Showing the status of links and options.

5.7.1 Searching for a source by regexp

You can search through the source buffer with s, which uses a regular expression. The prefix argument behaves just like for j and C-j: in fact, these are both implemented in terms of this command. In other words, with no prefix argument s will search ahead of the current source, while with a prefix argument, or if there is no current source, it will search through the current editing buffer from the beginning.

This command never searches from point onwards. You can always do C-u - prefix c first if you really want the effect of that --- that is, make the source immediately before point current first.

5.7.2 Unhighlighting the current link

You can turn off the current source/target pair with u (which stands for uncurrent), `deactivating' that link. This is recommended if you want to copy some text which includes the current source or target text, since the copied text will remain highlighted as if it were current, which is confusing. It also means sources will be searched for in the current buffer, rather than wherever the current source happens to be.

`Uncurrent' is a genuine and rather useful English word which has, unfortunately, fallen on hard times.

5.7.3 Inserting or displaying the source

You can insert the text highlighted in the current source into some other place (the "Search:" prompt in the minibuffer is a useful one) with i. The text retains its properties as a source wherever it is inserted, though the copy is not initially marked as current, hence it will be underlined but not otherwise highlighted.

The same command with a prefix argument just displays the current source in the minibuffer, useful to remind you what it is.

In fact, you can always copy or move cross-refs. anyway (see section C. Cutting and pasting cross-refs.); this is simply a short way of using the current source text.

Currently there is no corresponding command for the target text.

5.7.4 Status summary for the current buffer

Last but not least, the z command (for `ztatus', like the older Ultima(2) games) produces a buffer summarising Xref information for the buffer you are in: how many sources and targets there are in the current buffer, whether they have been altered (note it does not tell you whether the buffer itself was altered), how they will be saved (see section 6. Saving cross-references, below), what the settings of the main options are. This is a good way to retain some remnant of sanity during a marathon cross-referencing session.

5.8 Xref commands in restricted buffers

Searching for cross-references obeys restrictions. Hence, if you use the a command to go to the first source in the buffer, it will take you to the first source in the restriction, and if you use the j command to go to a particular cross-ref. it will only look at sources within the restriction.

However, some commands are supposed to take you to a given cross-ref., wherever it lies. In particular the g (go to the current source) and C-g (go to the current target) commands and others which use them (such as f, follow cross-ref.) do this. Since it would be rather obscure if you received a message such as `source appears to have been deleted' just because a source was outside the current restriction, Xref will instead remove the restriction entirely.

Restrictions are only removed when necessary. However, this may include making a source or target uncurrent, since the text needs to be accessed in order to change the face. Hence you may see apparently motiveless widening of a buffer when the current source or target lies outside a restriction.

6. Saving cross-references

Cross-refs. can either be written out in the file where the source or target they describe is located, or in a separate file for the whole directory, or in a single file in your home directory. The variable xref-external-save controls this; the default value is nil so that cross-refs. are saved in the visited file (unless it is not writable; see 6.2 Saving cross-refs. in another file).

Normally, you will just save the file you are editing and cross-refs. will automatically be saved at the same time. However, if the file is not marked as modified (for example, if you changed some cross-refs. but not the text of the file), then save-buffer (C-x C-s) will do nothing and you should use Xref's own C-s command. This will make sure cross-refs. are written out, but otherwise behaves just like save-buffer, including the use of the prefix argument.

Caution: ONCE A FILE HAS SAVED CROSS-REFS. YOU MUST BE SURE NOT TO EDIT IT WITHOUT XREF ACTIVE, or any sources and targets will be invalidated -- the locations of their starting points and lengths which are saved (see section D. Formats of saved cross-refs.) will not correspond to the altered text. Use the z command (see section 5.7.4 Status summary for the current buffer) to be sure. This should be obvious, but in case it isn't: only Emacs has the capabilities for keeping track of the sources and targets along with the text.

6.1 Saving cross-refs. in the visited file
6.2 Saving cross-refs. in another file
6.3 Controlling if, where and how Xref saves cross-refs.		If, where and how Xref saves cross-refs.
6.4 Brief summary of reading and saving cross-refs.		A brief summary of how Xref reads and saves things.

6.1 Saving cross-refs. in the visited file

By default, and providing the buffer is not read-only, when you save a file Xref tacks on the details of all the cross-refs. with sources in that file in a local-variable list: see the end of the file `xref.el' for an example. It will adapt any existing local-variable list.

If the buffer is read-only, Xref will save cross-refs. externally, as described in the next section. Thus C-x C-q is an easy way of persuading Xref to save a buffer's cross-refs. elsewhere without setting anything.

If there is no local-variable list, Xref will create its own. To choose an appropriate prefix and suffix, Xref will use any necessary comment syntax (e.g. semi-colons for Lisp) to hide the list from compilers etc. This uses the standard variables comment-start and comment-end.

If no comment syntax exists for the mode the buffer is in, Xref will use the variables xref-default-prefix and xref-default-suffix. You can redefine these to any strings you like; to turn them off, use the value "". The value "# " is used for the former as this is a very common comment syntax under UNIX. As an alternative to changing these variables you might consider defining your own values of comment-start and comment-end for modes which don't have them; I do this to make text mode use percent signs at the beginnings of lines.

Note that enable-local-variables should be t for cross-refs. saved in this fashion to be read back properly; this is the default, and if you have it set differently you should probably change the default value for xref-external-save (next section).

6.2 Saving cross-refs. in another file

If you'd rather not have your files modified, you can set xref-external-save. This is made local to every buffer for consistency, so to change the default value seen by new files you must use setq-default, which has no interactive counterpart; if you use setq or the interactive M-x set-variable command only the value in the editing buffer will be changed (which may be what you want).

If xref-external-save is t all cross-references are written to `~/.emacs-xrefs'. This is not very interesting, but human-readable enough for you to see what's happening where. If it is neither nil nor t, it be written into `.emacs-xrefs' in the directory where each file is. In this case, if the directory is not writable Xref will change xref-external-save to t; currently there is no way of preventing this. Under Oemacs, the filename becomes `_emacs.xrf'.

Hence, if you want to stick helpful links in `/etc/profile', say, they will be written in your home directory and `/etc/profile' will appear as hypertext to you alone. Of course, if someone else alters the file you're in trouble.

The name of the file, whatever directory is used, actually comes from xref-dot-file, which you can change if you don't like the default name. It can even be an absolute file name, or set in the local variable list, or for more control you can let xref-save-alist (see section 6.3.1 Saving different files in different places) do your work for you. Note, however, that changing the name makes it more difficult for other people to use your cross-refs., which would otherwise be easy if you save them in the same directory as the visited file. However, other people can make special arrangements by using xref-save-alist or xref-alternate-files too.

When a file is read back in, the value of xref-external-save is deduced by searching for cross-refs. for each file in the three possible places. If cross-refs. for the file were read in, wherever they came from, Xref will always try to save them in the same place, unless you explicitly set xref-external-save to something different. If you do, it is a good idea to delete the old list of cross-refs. by hand, wherever they were, unless you are simply copying a file.

You should also note that if the buffer was not modified, but there are cross-refs. to be saved which have been modified, then the buffer will be saved anyway, without offering you the choice. This is because kill-emacs-hook, Xref's way into the code which is run when you type C-x C-c, is called too late to be able to do anything else about it. The best way to avoid this is to kill the buffer first, answering `no' when Xref asks you if you want to save the cross-refs. If the buffer was modified, then C-x C-c prompts you and the choice of saving or discarding the buffer applies also to Xref.

6.3 Controlling if, where and how Xref saves cross-refs.

Make sure you understand the previous section before you read this.

6.3.1 Saving different files in different places
6.3.2 Checking other files for cross-refs.
6.3.3 Making Xref ignore changeable text at the start		Making Xref ignore changeable text.
6.3.4 Preventing Xref from writing cross-refs.
6.3.5 Reminder: which variables are buffer-local		Reminder of what needs setq-default.

6.3.1 Saving different files in different places

You can arrange for xref-external-save to be set to different values for different files by using the variable xref-save-alist. This is a list in the same format as auto-mode-alist, i.e.

(("file-pattern" . value) ...).

When you read a file, or save a file with cross-refs. for the first time, Xref will search to see if the file name matches one of the "file-pattern" regular expressions; if it does, xref-external-save for this buffer is set to the matching value. Only the first match is examined, so the order of the elements is important.

For example, if xref-save-alist contains (("^/users/" . t)) then Xref will try to save cross-refs. for files beginning `/users/' externally in your home directory. Note that any references to your home directory in the xref-save-alist "file-pattern" must already be expanded (tildes are not understood in the pattern): use expand-file-name for that purpose.

The value in an element of xref-save-alist may also be a string, in which case cross-refs. will be saved in a file of that name. If it is not an absolute file name it will be treated relative to the file whose cross-refs. are being saved. If you use this method, it is important that xref-save-alist is already set up when you reread the file, otherwise Xref will not know where to look for the cross-refs. The file name can be abbreviated; a ~/ reference is expanded internally. This method works by making the variable xref-dot-file local to the current buffer and changing it.

The most powerful way of using xref-save-alist is if the cdr of the element is itself a list, in which case it will be evaluated and the returned value used. The evaluation will always take place in the environment of the visited file for which the cross-refs. are to be read or saved, so you can use (buffer-file-name), etc.; for example,

(setq xref-save-alist (list (cons (concat "^" (expand-file-name "~/")) '(format "%s.xref" (buffer-file-name)))))

arranges that any files under your home directory will have their cross-refs. saved in a file of the same name with ".xref" appended on the end. Note that the (format ...) is quoted to avoid it being evaluated incorrectly when xref-save-alist is set. xref-save-alist should now look something like this:

(("^/users/hackers/pypeters/" format "%s.xref" (buffer-file-name)))

so if you don't want the value to be evaluated, make sure you remember the . in the element. Any errors in the evaluation are trapped; the error is printed in the minibuffer, but execution continues as if a t had been returned (the least dangerous option).

The default value of xref-save-alist is

(("^/[^/]*:" . t))

which matches Ange-FTP filenames and saves their links in your home directory. I find this useful because it is often difficult to tell whether a remotely-accessed file is really writable.

Note that xref-save-alist will take precedence over any value of xref-external-save you set yourself, because the check for a match is always carried out when the buffer is saved. One way round this is to set xref-save-xrefs to t locally, which tricks Xref into thinking there are already cross-refs. in the buffer which need to be saved where they came from regardless of xref-save-alist.

6.3.2 Checking other files for cross-refs.

The variable xref-alternate-files contains a list of file names each of which behave just like xref-dot-file. If the efforts previously described for finding cross-refs. fail, Xref will search the files in this list in order, either in the current directory or your home directory, for cross-refs. for the current file. If cross-refs. are found, xref-dot-file is locally set to the element of xref-alternate-files which matched.

The default value is (".emacs-xrefs" "_emacs.xrf"). This is particularly convenient for sharing sets of files between UNIX and DOS, as any file called `_emacs.xrf' imported into a UNIX system will be searched for cross-refs.. This saves you from having to make special arrangements via xref-save-alist for directories where you have DOS-compatible files.

(European readers should note the use of `alternate' rather than `alternative'; this usage is American but rolls more easily off the tongue here.)

6.3.3 Making Xref ignore changeable text at the start

If you send files containing cross-refs. through e-mail, or post them to Usenet (don't say I suggested this!), or have headers which are changed by systems out of Emacs' control, the length of text at the top of the file will vary. As Xref uses character counts to locate sources and targets this is unhelpful. For this reason, the variables xref-ignore-headers and xref-start-pattern exist for you to set when cross-refs. are saved in such a buffer.

xref-ignore-headers tells Xref to ignore the first paragraph up to the pattern specified by paragraph-start, so if you mail a file and the first paragraph fills up with `Received:' lines and such-like the offsets for the cross-refs. will remain correct.(3)

xref-ignore-headers can be a number, in which case Xref will ignore that number of paragraphs at the start.

xref-start-pattern is similar, but specifies a string to search for; all text before that is ignored. You will note that in the file `xref.el' everything before the `;;; Commentary:' line is ignored. This is useful when RCS modifies the `Id' string. In fact, the pattern matched does not need to be before all the cross-refs., since Xref will happily work with a negative offset. If xref-ignore-headers is a number, Xref will search for that many occurrences of the string and set the offset to the location after the last of those.

These two variables are buffer-local, like xref-external-save, so use setq-default to change the default values.

Both are automatically saved with the cross-ref. list, wherever that goes, so once either is set you don't need to make any further arrangements yourself.

6.3.4 Preventing Xref from writing cross-refs.

You can disable saving by setting xref-save to nil. Setting xref-active to nil is more wide-ranging: it stops all the hooks which Xref puts into Emacs to control reading and writing of cross-refs. and automatic display. Both of these are `unsafe' in that any cross-refs. will become out of date if the file was modified. Note also that setting xref-active to nil will inhibit xref-hks from loading the main package.

6.3.5 Reminder: which variables are buffer-local

To recap, the variables xref-external-save, xref-ignore-headers and xref-start-pattern are usually buffer-local as they must refer separately to individual files.(4) You should therefore use setq-default in your `.emacs' file to change the default, and setq or (interactively) M-x set-variable to change the value in a particular buffer.

None of xref-save, xref-active, or xref-save-alist is buffer-local by default. In fact, none of the other user options are usually buffer-local, only the three above.

xref-dot-file is only buffer-local if you have made it so, or if a match in xref-save-alist produced a new file name: that is, if the cdr of the alist that matched was a string or evaluated to a string.

6.4 Brief summary of reading and saving cross-refs.

When a file is read in, and either `xref' or `xref-hks' has been loaded, the following happens.(5)

1. If xref-active is nil, Xref does nothing.

2. If reading the file caused variables xref-1, xref-2, ... to be set(6), those are interpreted as containing cross-refs. in the format given in D. Formats of saved cross-refs.. The variable xref-read-xrefs is set to t, xref-external-save is set to nil (both local to the buffer) and no further search for cross-refs. is made.

3. The variable xref-save-alist is searched as described above in 6.3.1 Saving different files in different places. If the current file name matches, xref-external-save and (if necessary) xref-dot-file are set locally. Note that this happens whether or not the named file exists or contains cross-refs.

4. The file named by xref-dot-file (usually `.emacs-xrefs' or `_emacs.xrf') is looked for, first in the current directory (provided it is a relative file name), then in the home directory. If it exists and contains cross-refs. for the current file, they are read in, including values for xref-start-pattern and xref-ignore-headers. Then xref-read-xrefs is set locally to t and xref-external-save to either nohome (if cross-refs. were found in the current directory) or t (if they were found in the home directory) and searching stops.

5. Finally, Xref falls back on the variable xref-alternate-files, by default (".emacs-xrefs" "_emacs.xrf"). Each of these files is treated as a possible xref-dot-file in turn. If cross-refs. for the current file are found there, xref-dot-file is set locally to that file and handling procedes exactly as in the previous item.

6. If cross-refs. were not found, but a file in xref-alternate-files was found in the current directory different from xref-dot-file, the latter is set to the file found. (This may be overridden during the sequence for saving cross-refs., however.)

When a file is written out, the sequence of operations is as follows.

1. If either of xref-active or xref-save-xrefs is nil, Xref does nothing.

2. If xref-read-xrefs is t, usually because cross-refs. were previously read in, Xref does not work out where it should save cross-refs. but instead leaves the settings of xref-external-save and xref-dot-file as they were and the next three items are skipped.

3. Otherwise, the xref-save-alist variable is checked for matches; if a match is found, xref-external-save and xref-dot-file are altered as appropriate and the next two items skipped.

4. If xref-external-save is nil, but the buffer is read-only, Xref will change xref-external-save to nohome (if the current directory is writeable) or t (otherwise).

5. If xref-external-save is non-nil but the current directory is not writeable, the variable is changed to t.

6. If xref-read-xrefs is t or there are cross-refs. present in the current-buffer, Xref will now set up the appropriate file to receive the encoded cross-refs., save any that exist, and set xref-read-xrefs to t (since the file and the saved cross-refs. are now indistuingishable from a newly opened file with existing cross-refs.), which has the effect of freezing the value of xref-dot-file and xref-external-save.

7. Options

The variables associated with saving cross-refs. were given in 6.3 Controlling if, where and how Xref saves cross-refs.; this chapter lists the remaining options. Note that in contrast to many of the save options, which have to apply file by file, the variables here are not usually local to each buffer.

If it all gets too much for you, the z command gives the settings of some of the major user variables, see 5.7.4 Status summary for the current buffer.

All the user options can be altered by using the `customize' command, which means you can change the options without knowing any Emacs lisp. You will find the xref group of options inside the `Editing' group.

7.1 Options for tracking sources and targets		How to track sources and targets automatically.
7.2 Minor variables: highlighting, messages		Things you might want to set now and then.
7.3 Changing the appearance of sources and targets		How to change the way links look.
7.4 Circumventing woe with font-lock-mode

7.1 Options for tracking sources and targets

If xref-track-sources is set, as it is by default, then any command (c, a, e, n, p, s, j, l) which sets a new source but doesn't take you to its target will take you straight to the source. If it is nil, the cursor is left where it was but the new current source is still set. g will always take you to the source.

The variable xref-track-targets is similar but subtly different. Again, it only applies to commands which don't take you directly to the target. If set, setting a different current source will always display the corresponding target -- but in another window, which will not be selected. Thus there is no difficulty in having xref-track-sources and xref-track-targets set at once. Contrast this with the effect of the t command (see section 5.5 Commands which toggle options on and off) which causes this behaviour when the cursor simply moves into the source text.

Note that as the other window is not selected you cannot use the l command to go backwards over previous links when the targets were shown in this way. This could be changed but I think this is more consistent. I am not dogmatic about this, however.

xref-minibuf-auto-track is useful when your terminal does not support text highlighting. It is a flag to automatic tracking, so the t command (see section 5.5.1 Following cross-refs. automatically) must be in effect for it to be useful. If it is non-nil, moving the cursor into a source will show the source text in brackets in the minibuffer. If it is not t or nil, the usual effect of automatic tracking (showing the target in another window) is suppressed as well. It is set to t by default if Emacs is not running under a window system.

7.2 Minor variables: highlighting, messages

The remaining half-way useful variable is xref-highlight-current-target. As its name suggests, it controls whether the target of the current cross-ref. is highlighted. If it is nil, the target just appears as ordinary text. If you change its value, it takes effect at the next change of the current cross-ref. Contrast this with the h command (see section 5.5.2 Highlighting all targets of all cross-refs.), which highlights all targets, whether current or not; that is a function since it has to do some work to get that to happen. There is no corresponding source variable, but you can use v (see section 5.5.3 Making all cross-refs. invisible) to make everything disappear.

Setting xref-suppress-messages to t will prevent Xref from printing any of its usual informational messages in the minibuffer. This is probably most useful for calling Xref functions from other code.

Most variables not mentioned in this manual are for internal use; look through the file `xref.el' itself. You should think twice before setting them directly as most are intended to be manipulated by one or another Xref function.

7.3 Changing the appearance of sources and targets

The highlighting and underlining of sources and targets uses the standard Emacs 19/20 face code. You can use set-face-foreground, set-face-background, set-face-underline-p, etc. to change the appearance. See section `Using Multiple Typefaces' in The GNU Emacs Manual. You can now use the `customize' command to set faces along with other options.

The four faces normally used are xref-current-face and xref-face for sources, xref-current-target-face and xref-target-face (which is usually the same as the default) for targets. In addition, there are two faces used when a source and target appear on the same characters: xref-both-face if the target is not current, xref-current-both-face if it is.

For example,

(set-face-foreground 'xref-current-face "blue")

changes the colour of the foreground text used for the source of the current link. Under X windows (or DV/X, I presume) you have all the colours in `/usr/lib/X11/rgb.txt' (or wherever); under DOS, just the usual boring colours.

If you are not using the `customize' packet, you can use eval-after-load to do this sort of thing for you. For example,

(eval-after-load "xref" '(progn (set-face-foreground ...) ...))

which must be done before Xref is loaded. Also, you must make sure you load or require something called exactly `xref'; `xref-hks.el' does this, so you shouldn't have to worry. This has replaced the old (pre-Emacs-19) package-load-hook mechanism, so there is no xref-load-hook and never will be. (Note that eval-after-load doesn't currently exist in XEmacs; the underlying feature is there, but you have to manipulate the variable after-load-alist directly.)

Another way of altering the faces is to set the variable with the same name as the face to the name of another face, e.g.

(setq xref-face 'region)

or whatever. You can do this at anytime, for example in your `~/.emacs': no eval-after-load is needed. Unlike changing a face directly, it takes effect the next time Xref redisplays a single object in that face. Note that if Xref alters one of its faces, to make cross-refs. invisible (via v or to highlight all targets (via h), the face you use will be directly altered. For special effects, you can make these variables local to a buffer; Xref will then always use the faces appropriate to that buffer.

7.4 Circumventing woe with font-lock-mode

Many people use Emacs's font-lock-mode for colouring of syntax when editing programmes or the like; in fact, anything with syntax can be coloured. This is extremely useful. The advantage of font-lock over other packages is that the font is automatically updated as you type.

Unfortunately this can cause major problems for xref which needs to force the font for links to show up properly. In font-lock-mode, the font is lost.

It turns out there is a way around this which was implemented by Christoph Conrad. The normal way xref handles fonts and all its other information is using the text properties mechanism. This is ideal as text properties are transferred with text that is killed and yanked, so you can move links around. Unfortunately this is just the mechanism font-lock uses, and there is no way at the moment of telling font-lock to lay off a particular region. However, there is another mechanism for displaying a region of text in a special font called overlays. (In fact, xref was first implemented that way until RMS pointed out text properties were better.) Luckily, overlays can be used to override text properties. So if we use an overlay to add a special font, font-lock won't mess it up.

However, unlike text properties, overlays don't get copied with text. This is completely deliberate; overlays are a highlighting mechanism for a region of a file, not a way of associating values with text. So if xref just uses overlays, copied links won't show up straight away. They will the next time you read in the file, however, since all the information xref needs for its own purposes is there; only the display information is lost.

This means the default is to use both overlays and text properties to set the font. Then you can see what's going on in font-lock-mode, and in modes like text where font-lock-mode isn't so useful you can see copied links. If you are copying a link which occurs in text that font-lock will handle, however, you are out of luck. It looks like only a change to font-lock-mode will help here.

You can control what xref does using the variable xref-use-overlays. The values nil and t force xref never to use overlays, or always to use overlays, for fonts; any other value (such as the symbol both, which is the default) tells xref to use both. If you never use font-lock-mode, you could set this to nil to make xref work the way it was designed.

A. The Xref-bmk bookmarking package

A bookmark in Emacs term is a name attached to a location in some file. It's a bit like a cross-reference, except that the source is just a name, rather than a point in a file; you type the name, and Emacs takes you to that point in that file.

The package `bookmark.el' by Karl Fogel (referred to as Bookmark) implements this directly by using Elisp lists to hold the information. This appendix describes an alternative package `xref-bmk.el' (referred to as Xref-bmk) which uses Xref to implement the commands. The advantage of Xref-bmk is that the file where the bookmarks are saved is browsable and you can edit it directly or use Xref commands to handle your bookmarks. The advantage of `bookmark.el' is that it is smaller and faster, if you take into account that the whole of Xref is needed for Xref-bmk.

Xref-bmk is available from the sources given above for Xref, see 2.2 Acquiring the Xref package.

A.1 How to install Xref-bmk		How to install the Xref-bmk package.
A.2 Basic use of Xref-bmk		How to make and use bookmarks with Xref-bmk.
A.3 More advanced usage of Xref-bmk		The bookmark file itself, plus some options.
A.4 Comparing `bookmark.el' with `xref-bmk.el'		Important differences between the packages.

A.1 How to install Xref-bmk

Because Xref-bmk uses Xref for its functions, you need to make sure that Xref is loaded to deal with any cross-references it finds. By loading the `xref-hks' package, a small file which does just that, you make sure that this will append; see 2.3 How to set up Xref on your system above. Xref-bmk uses the same prefix key as Xref itself, so you must define that. Xref-hks will ensure that the main Xref package is loaded when you use that key; you can tell Emacs that you want it to load Xref-bmk at the same time. The following code in your `.emacs' file in your home directory will do this.

;; Make sure Xref-hks is loaded (require 'xref-hks) ;; Make sure Xref-bmk is hooked in when Xref loads (eval-after-load "xref" '(require 'xref-bmk)) ;; Pick a prefix key for all Xref commands (global-set-key [f8] 'xref-map) ;; In Xemacs, change [f8] to 'f8.

Xref-bmk will try to load Xref-hks if it finds that the main package is not present, so alternatively you can replace the first two of the three lines of code with (require 'xref-bmk) if you use Xref-bmk a lot. Xemacs currently doesn't have eval-after-load and you need to manipulate after-load-alist directly.

A.2 Basic use of Xref-bmk

You only need to know four interactive commands to use Xref-bmk. The keys shown are each prefixed by the key sequence you defined (f8 in the example).

+ (xref-bookmark-file)

Mark the current file, prompting you for the name of a bookmark. You are presented with the file name as a default. (Mnemonic: add a file.)

. (xref-bookmark-set)

Like <pfx> +, except the point in the file is remembered too, not just the file. (Mnemonic: make it point to point.)

= (xref-bookmark-jump)

Prompts for the name of an existing bookmark, with completion, and moves to the file or point marked by that bookmark. (Mnemonic: what does the bookmark equal?)

- (xrefb-bookmark-locate)

Prompt for a bookmark name, then insert the name of the file associated with that bookmark at point (just the name, not the whole file). (Mnemonic: dash off and find the name.)

Each time you set a bookmark the bookmark file is usually immediately updated and saved. If you try and use an existing bookmark as a new name, you will be asked whether you want to replace it.

A.3 More advanced usage of Xref-bmk

A.3.1 The file where bookmarks are saved		You can edit the file with the saved bookmarks.
A.3.2 Options controlling Xref-bmk		Options to set in Xref-bmk.

A.3.1 The file where bookmarks are saved

Bookmarks are usually written to the file `~/.xref-bookmarks', or `_xref.bmk' with Oemacs; the actual name is given by the variable xref-bookmark-file which you are free to change (even during use; the change takes effect immediately, so you can use different sets of bookmarks). You can look at this file and even change it. The actual information is saved in the local variable list at the end; the bookmark names appear highlighted with a windowing system. Editing these changes the bookmark name directly (but be careful that what you type is covered by the highlighted region; see the documentation on creating and replacing cross-ref sources, 5.2.1 Defining and moving sources, for more information).

Apart from this you are free to edit the file how you like; the file names written with the link names are simply for information. You can add lines or delete names (but see 5.2.6 Deleting links and their sources or targets for how to remove the links properly). You can also rearrange the lines by cutting and pasting.

There is one extra piece of magic: if the variable xref-bookmark-messages is non-nil, then whenever you jump to a bookmark Xref-bmk will look at the line in the bookmark file following the one with the name. If it begins with whitespace, the rest of the line is printed in the minibuffer. If xref-bookmark-messages is t, this happens every time you jump there, otherwise only when the file is first visited. For example, you may have something like

prog /machine.place.dom:/disk/users/me/progs/prog.c N.B.: this is under RCS control! Checkout locally before editing.

in which Xref-bmk added the first line and you put in the second. The message is from `N.B.' to the end of the line.

Two commands from the main package are particularly useful: the ones which follow a cross-ref. in the selected or another window. See section 5.3.4 Following the nearest source to its target, for help.

A.3.2 Options controlling Xref-bmk

For most people, Xref-bmk's default options will be the right ones; however, here is why they exist at all.

Unlike Bookmark, Xref-bmk has the capapbility for storing the location of the bookmarks pointed to (the targets, in Xref parlance) in the bookmarked files as a local variable list (like the one in `~/.xref-bookmarks'). This makes it easy to keep the points in the files which are marked up to date, even if you are not using the target yourself. However, although this is useful for ordinary cross-refs. it is probably unwanted for bookmarks, which should be as unobtrusive as possible (or ornamental, but that's hard on a computer :-)). For this reason the variable xref-bookmark-external exists and is usually t, ensuring that if a file is bookmarked but has no other cross-refs. in it the bookmark target will be saved in `~/.emacs-xrefs' (or whatever the value of xref-dot-file is), the standard file for targets of cross-refs. You can, however, set it to nil and the standard Xref variable xref-external-save (see section 6.2 Saving cross-refs. in another file) will be respected.

Note, however, that this is irrelevant if you use xref-bookmark-file (+) to mark bookmarks; only the file name needs to be remembered, which is naturally kept with the source of the cross-ref. in `~/.xref-bookmarks'.

Another property of Xref is that targets may be shared; this works around the problem that different targets can't overlap. If you use Xref only for bookmarks this probably needn't concern you. However, the variable xref-bookmark-delete-target exists. It is usually t so that if you replace a bookmark the target is deleted as well. If you set it to nil, the target will be left alone, just in case it was the target of another link.

There is also the variable xref-bookmark-save; this is t by default which means bookmarks are saved as soon as they are created. You can set it to nil, which simply means that you will have to reply `yes' when Emacs asks you if you want to save the bookmark file when you quit.

A.4 Comparing `bookmark.el' with `xref-bmk.el'

The basic functions of Xref-bmk -- xref-bookmark-set, xref-bookmark-jump, xref-bookmark-locate -- work like the corresponding commands in Bookmark. However, the underlying representation is completely different. Many of the book-keeping commands are replaced by direct editing or basic Xref commands. For example,

bookmark-insert

not supported; use xref-bookmark-jump and insert-buffer. (This is an Xref limitation.)

bookmark-rename

Just edit the name directly in xref-bookmark-file. Note that you must type inside the name for it to inherit the bookmark-ness. Or, use xref-set-current-source at this point, edit the name and use xref-source-word with a prefix argument.

bookmark-delete

You can delete the bookmark directly in `~/.xref-bookmarks', but that will leave the (harmless but useless) target marker, unless you used xref-bookmark-file which doesn't leave them. The safest thing to do is use xref-delete-selected (prefix C-d) with code `sfh' (`source', `follow', `here') on top of the bookmark before deleting it. If there's a chance the target might have some separate existence (i.e. you have other cross-references around) don't delete it.

bookmark-load

You can simply alter `~/.xref-bookmarks' if you want to use a different file, or visit a diffent file if you want to follow cross-references from it. Bookmarks are automatically loaded and saved with the file.

bookmark-write

Exactly the same applies here.

bookmark-save

xref-bookmark-save exists, but it has no effect other than saving the buffer visiting `~/.xref-bookmarks'. It's quite safe to save it by hand.

Saving `~/.xref-bookmarks' is a little problematic as if the file is unsaved at the point Emacs is killed, Emacs will ask you if you want to save it or not before xref gets the chance to save it automatically. (This is because of the point at which hooks are called in save-buffers-kill-emacs.) Just say you want to save it. To avoid hassle, Xref-bmk saves the file after every bookmark modification.

B. Summary of command names and bindings

Here are a list of all user functions, with their usual key binding and the where in the manual they are described. To change the binding, use something like

(define-key xref-map "C-c" 'xref-follow-xref) ; same as `f'

w (xref-source-word)

Make the word around or near point a new cross-ref. source: 5.2.1 Defining and moving sources .

r (xref-source-region)

Make the region a new cross-ref. source: 5.2.1 Defining and moving sources.

c (xref-set-current-source)

Make the source nearest to point current: 5.3.3 Setting a new current cross-reference.

a (xref-source-beginning)

Go to the first source in the current editing buffer: 5.3.2 Using ordered lists of sources.

n (xref-next-source)

Go to the next source after the current source: 5.3.2 Using ordered lists of sources

e (xref-source-end)

Go to the last source in the current editing buffer: 5.3.2 Using ordered lists of sources.

p (xref-previous-source)

Go the previous source before the current source: 5.3.2 Using ordered lists of sources.

g (xref-goto-current-source)

Go to the current source: 5.3.1 Going to an existing current cross-reference

o (xref-goto-current-source-other-window)

Go to the current source in another window: 5.3.1 Going to an existing current cross-reference.

x (xref-set-target)

Mark a single-character target for the current cross-ref. at point (not documented in this manual).

C-w (xref-target-word)

Make the word around or near point a new cross-ref. target: 5.2.2 Defining and moving targets.

C-r (xref-target-region)

Make the region a new cross-ref. target: 5.2.2 Defining and moving targets.

SPC (xref-target-file)

Make the current (or a specified) file into the target of the current cross-ref.: 5.2.3 Making a link point at a whole file.

C-x (xref-target-existing)

Reuse an existing target or the target of an existing source: 5.2.5 Reusing existing targets.

@ (xref-target-action)

Specify an action (Lisp, message or shell command) to be performed when the cross-ref. is followed: 5.2.4 Defining and editing action targets.

f (xref-follow-xref)

Follow the nearest source to its target: 5.3.4 Following the nearest source to its target.

mouse-1/button1 (xref-mouse-follow-xref)

Follow the source clicked with the mouse (only when on a source): 5.3.5 Following a cross-ref. with the mouse.

C-f (xref-follow-xref-other-window)

Follow the nearest source, displaying the target in another window: 5.3.4 Following the nearest source to its target.

mouse-3/button3 (xref-mouse-follow-xref-other-window)

Follow the source clicked with the mouse, displaying the target in another window (only when on a source): 5.3.5 Following a cross-ref. with the mouse.

C-a (xref-target-beginning)

Go to the target of the first source in the current editing buffer: 5.3.2 Using ordered lists of sources.

C-n (xref-next-target)

Go to the target of the next source after the current source: 5.3.2 Using ordered lists of sources

C-e (xref-target-end)

Go to the target of the last source in the current editing buffer: 5.3.2 Using ordered lists of sources.

C-p (xref-previous-target)

Go to the target of the previous cross-ref. before the current source: 5.3.2 Using ordered lists of sources.

C-g (xref-goto-current-target)

Go to the current target (the target of the current source): 5.3.1 Going to an existing current cross-reference

C-o (xref-goto-current-target-other-window)

Go to the current target in another window: 5.3.1 Going to an existing current cross-reference.

d (xref-delete-current)

Delete the current source and (without prefix argument) target: 5.2.6 Deleting links and their sources or targets.

C-d (xref-delete-selected)

Delete sources, targets or links according to the code specified: 5.2.6 Deleting links and their sources or targets.

s (xref-search-forward-source)

Search for a source containing the given expression: 5.7.1 Searching for a source by regexp.

j (xref-jump-source)

Jump to the cross-ref. source with the text given: 5.3.3 Setting a new current cross-reference.

C-j (xref-jump-target)

Jump to the target of the cross-ref. whose source has the given text: 5.3.3 Setting a new current cross-reference.

b (xref-back-to-mark)

Go back cyclically to the points from which an Xref movement command was made: 5.4.2 Going back where you were before an Xref command.

l (xref-last-xref)

Cycle back through previous cross-refs. which were current: 5.4.1 Going back through followed links.

C-l (xref-last-target)

Cycle back through previous targets found by Xref commands: 5.4.1 Going back through followed links.

t (xref-toggle-auto-track)

Toggle on/off the feature that makes targets appear in another window when the source text is entered: 5.5.1 Following cross-refs. automatically.

v (xref-toggle-invisible)

Toggle on/off invisibility of cross-refs: 5.5.3 Making all cross-refs. invisible.

h (xref-toggle-target-highlighting)

Toggle on/of highlighting of all targets: 5.5.2 Highlighting all targets of all cross-refs..

m (xref-toggle-xref-map)

Toggle the Xref keymap onto/off the main keymap: 5.5.4 Putting Xref's keymap onto the main one.

u (xref-uncurrent)

Make no cross-ref. current: 5.7.2 Unhighlighting the current link.

i (xref-insert-source-text)

Insert (display) the text of the current source: 5.7.3 Inserting or displaying the source.

s (xref-save-buffer)

Save the current buffer, making sure any modified cross-refs. are written out: 6. Saving cross-references.

z (xref-status)

Display information about cross-ref. links and settings in the current buffer: 5.7.4 Status summary for the current buffer.

none (xref-popup-menu)

Call up a menu of Xref functions to select with the mouse: 5.6 Selecting commands from a menu.

C. Cutting and pasting cross-refs.

[This appendix is in case you have any problems; you probably don't want to read further than the end of the next paragraph otherwise.]

Cutting and pasting of both sources and targets is supported, and generally you can do any reasonable editing on files containing them. For example, if you delete them they're gone for ever, although you can pull them off the kill ring as many times as you like while they're still there.

Moving sources is not expected to cause any problems at all, nor is moving targets within the same buffer. Moving a target to a different buffer should also work: Xref will usually save a pointer in the original buffer, so that any sources still pointing to the target in its original location will find it. If there is no such source, the pointer is useless but harmless.

When copying sources or targets, it is best to make sure they are not marked as current first, or the copies are likely to retain the distinctive typefaces even when the current cross-ref. changes.

Copying a source creates a new source with the same target as the original.

Copying a target is the most difficult part, because it is hard to tell which of the two any existing sources are meant to have as target. If the new target is in the same buffer as the old one, the first of the two copies encountered will be used as the target but the second will be remembered and saved. If it is in another buffer, the new target will usually be ignored.

However, there is one piece of magic which occurs when cross-refs. are saved (only): if a target is copied and there is a source pointing to it in the new buffer then the copied target becomes a separate target pointed to by the source in that buffer. In other words, if you copy both a source and a target to a new buffer and save them you have created separate links inside both the original file and the new file. Likewise, if you write a buffer under a new name any source/target pairs will be preserved within both the original and newly-written file. In no other circumstances, including any time when the source and target are in different files, are new source/target pairs created. (Well, I did tell you you didn't want to read this.)

Be warned that if you copy just the source of a cross-ref. to a new file an inter-file link to the original target will always be created.

D. Formats of saved cross-refs.

It is unlikely you will need to know this unless you are planning on converting the Xref format to something else. Even then, you might consider doing so in Lisp using Xref's own internal functions, rather than on the saved data.

For cross-refs. saved in the visited file, `xref.el' acts as an example. When Xref saves to a local variable list it does so by creating a sequence of variables which are examined in turn when the file is revisited, so the variables must increase continuously from 1. The value is the cross-ref.

Note that the local variable entries for xref-start-pattern and xref-ignore-headers, if either is non-nil, must come before any cross-refs. to ensure any offsets are correct.

If cross-refs. are saved to a separate file, the individual sources and targets are exactly the same. They are the elements of a list, one for each file, which is headed by any variables that need to be set as a (variable . value) cons cell. Before the list comes the text `File: filename': note that this is not read as Lisp code, and must appear in exactly that fashion with no quoting and no extra white space. This is so filenames can be searched for without reading the data for all cross-refs. as Lisp code at once. To get an easy example of this, visit `xref.el', set xref-external-save to t, then visit `~/.emacs-xrefs' (but don't change `xref.el' while xref-external-save is t).

D.1 Format of saved targets		Format of saved cross-ref. targets.
D.2 Format of saved sources		Format of saved cross-ref. sources.

D.1 Format of saved targets

If the list begins with a t, it's a target (try to forget that, if you can); these are always saved first.

The number after that is the position in the file where the target starts, with any necessary offset given by xref-ignore-headers and/or xref-start-pattern subtracted. You can retrieve this offset for the current editing buffer using the function xref-get-offset. The next number is the length of the target.

The final number is an identification number which is local to each separate file. When the target is read in, it is assigned a different global identification number which is specific to each Emacs session. This allows you to handle any combination of different files at different times. The list xref-target-list contains separate alists of local/global target ID pairs for each buffer.(7)

Instead of the first two numbers there may be a list which looks like ("file_name" id) which says that the target has moved to another file with the given local ID.

To summarise, a normal target looks like

(t start-minus-offset length local-target-id)

and a pointer target looks like

(t ("new-file-name" new-local-target-id) old-local-target-id)

D.2 Format of saved sources

The sources don't begin with a t. The two numbers are the same as for targets (previous section). Then comes a list which specifies where the target of the source is to be found; it usually looks like ("file-name" id), but the file name will be missed out if the target is in the same file as the source. The id is the local target identifier in the appropriate file. The target may be a string instead of a list, in which case it is an action just as it was typed in. To summarise, a source linked to some other buffer looks like:

(start-minus-offset length ("target-file-name" local-target-id))

and a source linked to the same buffer looks like:

(start-minus-offset length (local-target-id))

and a source with an action target looks like:

(start-minus-offset length "action-string")

so that sources always have their own distinct action target where applicable.

E. Some tips on using Xref

Here are a couple of things I've learnt after a few months of playing with Xref which might prove useful.

E.1 Misaligned cross-refs.		Fixing cross-refs. which appear in the wrong place.
E.2 Transferring a file from DOS		Making sure carriage returns are removed.

E.1 Misaligned cross-refs.

Sometimes you may find that when your read a file the cross-refs. after a particular point appear out of place by a few characters. This happens if some text changes while the file is not under Emacs control. You can usually fix this without laboriously moving the sources and targets by hand. One procedure is:

1. Count how far the cross-refs. are out of alignment; call this offset.

2. Set the variable xref-active to nil.

3. Find a point after the last cross-ref. which is correct (if any) and before the first which is wrong (don't forget possible targets).

4. If the following cross-refs. appear before the text on which they should appear, use M-w to remove offset characters at the point chosen; if the cross-refs. are after where they should be, add some easily identifiable garbage offset characters long.

5. Save the file, kill the buffer and revisit the file.

6. Set xref-active back to t.

7. Restore or remove the bits you modified.

8. Save the file again.

9. Repeat the previous items as many times as necessary to restore the cross-refs.

E.2 Transferring a file from DOS

When editing under DOS, Emacs doesn't recognise the extra carriage returns that DOS uses as being part of the buffer. This means that if you bring the file to some computer with a real operating system (and certainly any version of UNIX) you have to make sure those carriage returns are disposed of carefully.

This will usually be done for you if you use FTP in `ascii' mode. On a Sun workstation the command `dos2unix' will do it for you. On other UNIX systems you can use some command such as perl -pe 's/\r\n/\n/' dosfile > unixfile. If you don't have Perl see if your sed understands `\r'; not all do. You can also use some package (such as crypt++) which will recognise and handle the format before Xref sees the buffer.

Transferring back to DOS is not a problem as Oemacs and other DOS versions of Emacs are happy with or without the carriage returns.

F. Bugs

Some of the following are easier to fix than others, so don't count on all of them disappearing soon.

• If you copy a target to a new file, save both the files, and later on delete the original target, the copy will not be used; there is no mechanism for stacking targets other than by their order in a single file. The latter should be regarded as an aberration rather than the former as a bug.

• Inserted files (C-x i) do not have cross-references expanded. To get round this, visit the file then insert the corresponding buffer (C-x C-f followed by M-x insert-buffer).

• Other limitations, for example commands which could handle prefix arguments in some more logical way, are noted in the source code.

G. Things to do

These are just ideas. Many will never happen unless you write something yourself and send it to me; others are probably completely unnecessary. See section 1.2 How to submit feedback about Xref.

• Some of that hackery w3 uses to get underlining etc. on dumb terminals. This looks fairly hairy at the moment.

• Narrowing. xref-narrow to determine initial narrowing; each target to have optional narrowing information stored. This would allow an Info-like node structure; by inheriting restrictions it could still all be done with keystrokes.

• xref-track-sources should at least provide the option of tracking sources in the other window, like xref-track-targets, perhaps.

• Relative file names. Save without full path: option. Currently all files in the same directory have no path, otherwise a full path. Use of abbreviated file names in dot-files.

• Commands for searching all buffers for a particular source, or searching without regard to restrictions, are certainly feasible.

• Hooks of one kind or another (e.g. xref-new-current-hook, xref-new-source-hook, or functions which are passed the beginning and end of regions). Vote now: I don't really need these, since I can modify the source directly :-).

• An etags to Xref (or v.v.?) converter has been suggested. This wouldn't need to be part of the standard package. Even more useful might be an Xref to HTML converter -- this would allow a completely keyboard driven way of making hypertext documents (but c.f. Hyperbole for proper HTML handling).

• Functions which use the order of the targets in the current buffer; some way of going `up', i.e. back from a buffer with given targets. This would be for info and wouldn't need to be fast (to do it fast, create a reverse source/target pair -- probably unnecessary).

• Footnotes: facility for creating a target to the current source at the end of the file, or in some designated file.

• Using the new Emacs primitives for writing and reading text properties to make a way of reading/writing cross-refs. from/to the text file without using the local variable list. Still requires some way of handling xref-ignore-headers etc.; also probably not useful when saving externally. Also more invasive, perhaps unnecessarily so.

Joke

How to Shoot Yourself in the Foot (Which Language is for You): Addendum.

Lisp: Your leg is really (hip thigh knee shin ankle foot). You search through the leg until you find a foot. You remove the foot from the leg and wait for the garbage collection. The gun was pointing at something else anyway.

Concept index

Jump to:	.   _   A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W   X

Variable index

Jump to:	C   X

Footnotes

(1)

Note that it is not possible to use global-set-key interactively to bind to xref-map, since Emacs does not consider the latter an interactive function.

(2)

Ultima is a trademark of Origin Systems, Inc.

(3)

Remember, however, that Sendmail replaces any `From' at the beginning of a line with `>From'. You're on your own there, but for some tips on fixing this, see E.1 Misaligned cross-refs.. The trick with TeX code is to change this to `{}From' before you send the file.

(4)

If you don't believe this, think about what happens when you change the values, save the files, then later read them in during a different session; they have to be buffer-local then. It is far less confusing to have them buffer-local from the start.

(5)

Actually, if you are using Xref-hks, this needs to happen twice: once to see if there really are cross-refs. before the main package is loaded, then again to read the cross-refs. in.

(6)

Actually, that xref in the name is the value of xref-local-var; you probably don't want to change it unless you need a special effect.

(7)

An alternative would have been to generate unique non-numeric IDs for targets. These would necessarily have been somewhat bulky.

Table of Contents

Introduction

1.0 Possible uses for Xref
1.1 Things that Xref is not designed for
1.2 How to submit feedback about Xref
1.3 Acknowledgements

2. Preliminaries

2.1 Requirements for running Xref
2.2 Acquiring the Xref package
2.3 How to set up Xref on your system

3. Basic ideas
4. A lightning tour of Xref
5. A less brief introduction to Xref commands

5.1 Conventions for keys and commands
5.2 Making, moving and deleting sources and their targets

5.2.1 Defining and moving sources
5.2.2 Defining and moving targets
5.2.3 Making a link point at a whole file
5.2.4 Defining and editing action targets
5.2.5 Reusing existing targets
5.2.6 Deleting links and their sources or targets

5.3 Commands to move between sources and targets

5.3.1 Going to an existing current cross-reference
5.3.2 Using ordered lists of sources
5.3.3 Setting a new current cross-reference
5.3.4 Following the nearest source to its target
5.3.5 Following a cross-ref. with the mouse

5.4 Going back to previous links and points

5.4.1 Going back through followed links
5.4.2 Going back where you were before an Xref command

5.5 Commands which toggle options on and off

5.5.1 Following cross-refs. automatically
5.5.2 Highlighting all targets of all cross-refs.
5.5.3 Making all cross-refs. invisible
5.5.4 Putting Xref's keymap onto the main one

5.6 Selecting commands from a menu

5.6.1 Using Xref commands from the menu bar
5.6.2 Using Xref commands with a mouse event

5.7 Miscellaneous commands (searching, inserting, status)

5.7.1 Searching for a source by regexp
5.7.2 Unhighlighting the current link
5.7.3 Inserting or displaying the source
5.7.4 Status summary for the current buffer

5.8 Xref commands in restricted buffers

6. Saving cross-references

6.1 Saving cross-refs. in the visited file
6.2 Saving cross-refs. in another file
6.3 Controlling if, where and how Xref saves cross-refs.

6.3.1 Saving different files in different places
6.3.2 Checking other files for cross-refs.
6.3.3 Making Xref ignore changeable text at the start
6.3.4 Preventing Xref from writing cross-refs.
6.3.5 Reminder: which variables are buffer-local

6.4 Brief summary of reading and saving cross-refs.

7. Options

7.1 Options for tracking sources and targets
7.2 Minor variables: highlighting, messages
7.3 Changing the appearance of sources and targets
7.4 Circumventing woe with font-lock-mode

A. The Xref-bmk bookmarking package

A.1 How to install Xref-bmk
A.2 Basic use of Xref-bmk
A.3 More advanced usage of Xref-bmk

A.3.1 The file where bookmarks are saved
A.3.2 Options controlling Xref-bmk

A.4 Comparing `bookmark.el' with `xref-bmk.el'

B. Summary of command names and bindings
C. Cutting and pasting cross-refs.
D. Formats of saved cross-refs.

D.1 Format of saved targets
D.2 Format of saved sources

E. Some tips on using Xref

E.1 Misaligned cross-refs.
E.2 Transferring a file from DOS

F. Bugs
G. Things to do
Joke
Concept index
Variable index

Short Table of Contents

Introduction
2. Preliminaries
3. Basic ideas
4. A lightning tour of Xref
5. A less brief introduction to Xref commands
6. Saving cross-references
7. Options
A. The Xref-bmk bookmarking package
B. Summary of command names and bindings
C. Cutting and pasting cross-refs.
D. Formats of saved cross-refs.
E. Some tips on using Xref
F. Bugs
G. Things to do
Joke
Concept index
Variable index

About this document

• 1. Section One
• 1.1 Subsection One-One
• ...
• 1.2 Subsection One-Two
• 1.2.1 Subsubsection One-Two-One
• 1.2.2 Subsubsection One-Two-Two
• 1.2.3 Subsubsection One-Two-Three     <== Current Position
• 1.2.4 Subsubsection One-Two-Four
• 1.3 Subsection One-Three
• ...
• 1.4 Subsection One-Four