[Discussion] Cross referencing

[mc7121]

What possibly may be a problem is not calculating 1,500 CRs (or 15,000, for that matter) but paginating and organising text correctly. For example, if you have a CR on page 14, referencing the page number on page 99. You add a sentence before this, so the length of the text on page 14 causes two lines to be moved into page 15 and the whole thing moves a page forward. Now you have a reference not to page 99 but to page 100 -- another letter is added, which may cause the text to move yet one page more, and so on. Those are the "danger" cases that need to be controlled.

This gets even worse when CRs support context sensitive relative texts like "previous page", "next page". If - and I consider this to be very very usful - CRs can say "see figure on previous page" or "see figure on page 28" depending on how far the referenced object is away, the reference texts vary even greater in length and run into danger of messing the entire layout.
For that reason I think it is an absolute requirement to have the CRs update their textual representation dynamically while you write.

From a technical point of view, I think this update should not consume any notable processor time. I would implement that using a classic Observer Design Pattern, where a CR registers itself with the referenced object. Whenever the referenced object is changed, it calls the registered (observing) CRs and tells them to update. I'm sure something like this already happens a lot in Mellel right now.
I think Mellel solved more difficult tasks before so I'm confident they get it done as nicely as so many other things.

[mc7121]

How it works
To have a cross reference you need two things: A) Somewhere from which you refer. and B) Something to refer to... Which leads to C) A mechanism to connect A and B.

I would like to elaborate a little on the mechanism part as I think that's where Mellel can provide some valuable extra benefits with reasonable effort.

The CR's representations should
1. be relative depending on the location of the reference and the referenced object.
Example:
Assume we reference figure 3 (referenced object) which is located on page 21.
If the reference is on page 22 it should be able to read "see figure 3 on previous page" or "see figure 3 above".
If the reference is further down - say page 30 - is should be able to read "see figure 3 on page 22"
2. handle ranges
Example:
Assume we reference chapter 3.1 (referenced object) which stretches from page 41 to 47.
In this case, the reference should be able to either read "see chapter 3.1 on pages 41 to 47", "see chapter 3.1. starting at page 41" or "see chapter 3.1. on page 41ff". The last expression should only read "page 41f", however, if the chapter only stretched from page 41 to 42.
3. support abbreviations
A referenced object should know its description along with its abbreviations. E.g. a figure should know its label is "figure" and its abbreviation is "fig.". This way, the reference should be able to read "see figure 3 on page 22" or "see fig. 3 on p. 22"
4. support levels
Example:
Assume we reference figure 3 (referenced object) which is located on page 21.
A reference should be able to read "see figure 3 on page 21", "see figure 3 in chapter 2.8 on page 21" or "see figure 3 in chapter 2.8"

All of these options result in a lot of posible combinations. So how do you provide a good and consistant user interface for that? Simply by using what's there already: the auto-title setup.
Tokens
I suggest using the notions of tokens as in the auto title setup. A token could represent static text like "see", all the dynamic elements like levels and the characteristics like abbreviated or not.
Styles
The user should be able to define a couple of cross reference styles with the above mentioned options. Each style could offer the elements from above using these tokens. User could define one style as a default. When adding a CR with a short cut (using the keyboard or from a palette), the default style would apply. In addition to that, the CR palette would show all styles so the user simply has to double click on one to add a CR at the cursor position.

As mentioned in a previous posting, it is a requirement for the implementation to update CR dynamically while you write to cope with this functionality's effects on the layout.

[mc7121]

Probably the question of questions: When will we see the first CR implementation? I'm not asking for exact dates but is it a matter of weeks, few months, some months or many months?
I'm asking since I have to submit my dissertation early next year. I could wait until about the end of this year, but after that I really don't know what to do because I heavily depend on cross references in an extent that can't be handled manually.

[KimU]

Hopefully this isn't too pesky - but I'm in the same boat as mc7121 (except with an earlier deadline). Any suggestions on the time frame for implementing this?

As for functionality, the things that I personally need are pretty basic. I just want to be able to refer to auto-titled items (tables, figures) within my text and have automatic updating when I do that.

[Reiner]

Hadn't Ori told us that the plan is to implement this within 2006? Look in the newsletters or in the forum, I can't remember at the moment.

[Ori Redler]

Hadn't Ori told us that the plan is to implement this within 2006? Look in the newsletters or in the forum, I can't remember at the moment.

Indeed!

[matthias]

With regard to cross referencing, one thing has been on my mind for quite some time. This concerns CRs in bibliographical references (in footnotes, or as in-text-citations). On many occasions, only the first citation of a particular reference will include the full bibliographical data.

E.g.:
2 Tawhida, Ahmed/de Israel, Jesus Butler: The European Union and Human Rights: An International Law Perspective, in: EJIL 17 (2006), S. 771-801.

Any subsequent citation will, for instance, include the author's name, a page number, and a CR to the first citation of the reference.

E.g.:
45 A. Tawhida, J. B. de Israel, EJIL 2006, (supra note 2), p. 771.

While formatting as such can be handled by Bookends – in this app you can define a separate format for references cited more than once – and cross referencing will be by Mellel, I wonder whether the interaction of both could be enhanced, as well. As things will stand by the time Mellel will have implemented CR, I will have to go through a final paper after scanning it with Bookends, find all cases where a reference has been cited twice or more often, and insert the CRs by hand. Now I could think of a way to expedite this procedure.

Mellel could improve its Bibliography functionality. For instance, something called like "citation cross reference" could be implemented: When inserting a second citation of a reference, Mellel could come up with some kind of "CR warning" and offer to insert a CR right into the Edit Citation dialogue box. Of course, CRs could only be inserted either at the beginning or at the end of a preliminary citation, but still it would be an improvement. And I don't know whether a CR could be inserted in a preliminary citation at all, and whether it would "survive" whatever Mellel and Bookends do with it while scanning. But I think something along these lines would be a great time saver, so I dropped my thoughts to see what others (in particular the Redlers re feasibility of this) think think about it…

matthias

[Phil82]

Any idea on the estimated time of arrival of cross referencing?

[danzac]

Any idea on the estimated time of arrival of cross referencing?

Well unless the Redlers are liars, I would hedge my bets that it will arrive sometime in the next 46 days!

[Mart°n]

To jump into the discussion right before the next version of Mellel jumps out of the box, I’d like to post my wishes. Most things (if not all – maybe I’ve overlooked the one or the other) have already been said but I will note them anyway if the Redlers use an “importance counter” to see how often a feature was requested. Here we go:

• Live update would be great and give you the complete control over the final layout. I would like to see the same for TOC creation but that’s another point. As even oder Macs should be able to do this in real-time, I’m all for it.

• Inserting Cross References should be possible via a keyboard shortcut or via a some sort of drag and drop method. I think Mellel to far of those user interface actions, where you could see what you are actually doing to which portion of the text. This lead to:

• Viewing Cross References. I would like to see where a cross reference is (maybe via a small icon or a colored border around the reference itself) and also the part it references to, so that I easily could see, if I delete a reference or a referenced part if I delete some text. A warning window shouldn’t be necessary in this case.

• Jumping between the reference and the referenced part should be possible. It could work like it works with notes already or be implemented with a single click action. If one hovers over a reference (or the referenced part), a small circled arrow icon could appear (roll over effect) and if I click that icon, I will be beamed to the other side of the galaxy (or cross reference, if the galaxy part is too difficult) .


If you move your mouse over a cross reference (green thing), a small pop up menu will appear, where you could jump to the other end, open up the editing window, show another pop up menu with some lines of the referenced part to actually see what’s on the other end of the reference and delete the reference. The menu won’t be visible if you only write your text and don’t hove over the reference with you mouse. You could disable the green highlight color as you could disable the red spell checker highlight or the grey auto-title color.

• Editing Cross References should be possible without re-creating them (maybe via a cross reference palette or window where you could see all of them, alter their reference and the location they are referencing to and see at a glance, if one reference is broken)

• Dynamic description that changes with the position of the referenced part (see next page, see page 21,…). Those elements should be present in various languages and maybe you should be able to edit them.

• Two way references. On page 2 I would point to page 21 (see page 21) and on page 21 I would point back to page 2 (see page 2).

• Split Screen. It would be great, if a split screen feature would be integrated at the same time. With such a thing, you could insert a reference on page 5 and see the referenced part on page 87 at the same time (if you need to select the referenced text or if you like to insert the second reference via drag and drop…)

• URL-links. Not really cross-references, but I would like to see clickable URL and MailTo Links built in.

• PDF-Export. It would be really great, if Mellel gets an enchanced PDF export with working links so that you could click URLs, TOC entries, Notes and Cross References and jump to the referenced position (or open a website/mail client).

That’s it. Thanks for reading.

[macsailor]

Well unless the Redlers are liars, I would hedge my bets that it will arrive sometime in the next 46 days!

I would not call them liars even if they missed a deadline or two. It's better to have really good implementation of new features within the already excellent Mellel, than to manage to meet the deadline and ending up getting features that does not work as they were supposed to work.

Redlers, I'm ready when you're ready.

[Nick Sloan]

Some people above have expressed a hope for references that span Mellel documents. I don’t know how easy this would be to achieve, but it would represent a great leap in the potential scope of information referenced. It would also mean that you could see two pieces of text simultaneously, so that in theory you could keep visible references in one document while you work on your main text in another. (For an excellent precedent for this sort of linking, see Circus Ponies NoteBook, where you can do it simply by option-control-clicking from one cell to another.)

If that is asking too much for now, please could we at least have links to external files: click on the link and the document/folder opens in the Finder. This is something that all self-respecting outliners and info-archivers have offered for a long time, and it can be incredibly useful. For one thing, it would be a halfway house to inter-document CRs, and for another you could reference illustrations without having to import them.

[rpcameron]

• URL-links. Not really cross-references, but I would like to see clickable URL and MailTo Links built in.

• PDF-Export. It would be really great, if Mellel gets an enchanced PDF export with working links so that you could click URLs, TOC entries, Notes and Cross References and jump to the referenced position (or open a website/mail client).

To the first of these requests, I must say I vehemently disagree. One of the features I hate about Word is that it creates clickable links when you type an email address or URL/URI. Very rarely (if ever!) do I want my word processor to make my typographically beautiful document to be marred by blue text with unsightly underlines. If this were to be implemented, it would need to be an option, with the default being off. (Or better, links, especially to an outside program like an email address or URL/URI, should need to be explicitly created.)

As far as the second part, it would be nice to create a new PDF export system that embeds the TOC and allows for navigation within the document by using the TOC.

[Reiner]

Or better, links, especially to an outside program like an email address or URL/URI, should need to be explicitly created.

this is exactly the way I would expect Mellel to embed this feature, which I also would like to see.

[Mart°n]

[
To the first of these requests, I must say I vehemently disagree. One of the features I hate about Word is that it creates clickable links when you type an email address or URL/URI. Very rarely (if ever!) do I want my word processor to make my typographically beautiful document to be marred by blue text with unsightly underlines. If this were to be implemented, it would need to be an option, with the default being off. (Or better, links, especially to an outside program like an email address or URL/URI, should need to be explicitly created.)

I completely agree with you. I also hate the auto-links created by some apps and hate even more their blue color and ugly underlining. I also rarely need those features but if I create a PDF, I would like to be able to make URLs clickable (for example in the list of references, so the reader don’t have to select the url and copy&paste it into a browser window).
As I like to see those “references” to be a part of cross references, you only could create them by demand (as in InDesign, for example). An automatic link detection is nothing I’m interested in (at least in Mellel).