[Discussion] Cross referencing

[Ori Redler]

Excellent summaries about what is needed for cross references. I still do not see how to find the referred object quickly, this is why I suggested to make them visible tags (and invisible again) in the outline.

In Nisus I did not use cross referencing intensively because after a while it became impossible to keep track of all marked text in one list for a 800 page text.

One always has an idea about in which part of the text the referred part is. So it should be easy to e.g. cmd-click on a section ( chapter) triangle or header in the outliner and get a list of all referenced texts in this particular section. The list would be much shorter than for the whole book.

Maybe I am stuck in the Nisus paradigm, but I do not see any other way than with such a list -- if one will not have to move manually to the part referred to (which would need split screen btw).

Your ideas please.

Maria

The question of tracking and navigation between CRs is crucial, but should be separated, IMO, from the "core implementation" that deals with insertion and formatting of CRs.

There are a few possible options for dealing with tracking and navigation:
A. A simple list of "marked" text.
B. Utilising Find and Replace.
C. Listing CRs in the outline pane, either within chapters or separately (much like figures today).
D. A separate pane for CRs, with marking for "incoming" (referred to) and "outgoing" (referring) CRs. That can come with or without "rude" separation (e.g., by chapters) of CRs.
E. A "jump" system from referrer to referred.

Of course, most of those are not mutually exclusive.

[Ori Redler]

Hello,

Having read this thread, two things spring to mind:

1: I definitely recommend not having automatic updating of crossreferences, but to update the crossreferences prior to saving or printing, and to have some kind of "Update references" button or menu command. Take a look at Adobe Framemaker, and how it is implemented there.

2: Regarding crossreferences, what would be extremely nice is to emulate the "varioref" LaTeX package. If the crossreference's target is on the previous page or on the next page, the text is changed from, say, "See Figure 5 on page 35" to "See Figure 5 on the previous page", and "on the next page", respectively. If the publication uses recto/verso printing and the crossreference's target is on a facing page, the text will be "See Figure 5 on the facing page". And lastly, if the crossreference's target is above or below the crossreference on the same page, the text is changed to "See Figure 5 above", and "See Figure 5 below", respectively. This change of crossreferece texts can take place when updating the references.

Best regards,
Mats Broberg

I think that options to state "relative position" of the CR versus that referred item (text, object, etc) is important.

I am wondering, however, why it seems that obvious to so many that the CR should update when printing or saving and not immediately. If we cannot supply a decent speed with immediate updates of CRs we would not update immediately, of course, but why forfeit this in advance?

[mikejt]

Hey, very cool, all of them ...

Quick background: I've used (extensively) the FrameMaker methodology and find it more than acceptable. If Mellel copied it, I would be happy as a clam (particularly how stable, flexible, and fast that system is). I've also used Word's methods, and they are OK for entry, but management and after-the-fact editing are not pleasant experiences. Please do not use those as your model.

On to the details:

Items you can refer to:
• Auto-title (heading, figure, etc.)
• Arbitrary item (blank)
• Objects (citations, notes, any other object).
• Marked text.
• Page

That can be easily extended to allow one to refer to a line number, list, par. or char. style, and so on). The main question is if any of those is needed.

Well, I'd try to mimimize the choices, but probably in a higher level way ... if an Auto-title or citation or list was an attribute of a paragraph style, rather than being things isolated in the object hierarchy, you could have as your list:
• Paragraph Style
• Tagged text (marked text?) ... whatever you use for index marking
The "page" really should be extracted as part of the CR format ("$pageof" variable)

Entry:
There should be options to:
A. Choose the type of item to refer to.
B. Choose a format of reference (i.e., to what aspect of the referred item you refer).
C. Edit and add to the formats of reference

One should be able, when entering a blank reference, to name it.

To enter entry of CR there should be an easy and obvious option (Cmd+something). To edit, a similar command or double clicking should be available.

Excellent! As part of the format creation process there should be variables for page#, line#, autotitle number (the x.x.x thing), full autotitle sequence ("figure x-y"), and others (check the FM methods)

Managing:
There should be a way to view all CRs, either via a pane or via a palette. The list should differentiate "blank" CRs and directed CR. The format should be something like:
p. 212 -- > figure 12, p. 23

Or,

p. 213 --> Part about Horatio (ch.18) (that is, to the name of the blank reference).

To link blank references, one could go to the place where they should refer to and "link" them. This should be done, probably, via a "mark" option that would list the blank references and allow one to choose any of them and thus create a link.

Very good! This would make searching through CRs much nicer (of course you would have flags for "lost reference").

Updating
Should be immediate, in my view.

OK, but NOT required. I would much prefer speed to auto update.

[Normand]

When I add an item and the autonumbers and/or cross-refs do not update instantly it makes me feel that something is going wrong. I am not an expert and there must be some reasons but I don't see good reasons to postpone the updationg.
Modern computers are fast machines.
And there is no need to scan continuously the document to update the cross-refs; doing that only when a cross ref is added would suffice.

Normand

[zoul]

And there is no need to scan continuously the document to update the cross-refs; doing that only when a cross ref is added would suffice.

Unfortunately this is not exactly true. Imagine yourself adding some text to the beginning of a long document. If the referenced objects get pushed to a different page, their references have to be updated, because they could use the page number. This potentially means watching the references for changes after each document change, which could be expensive.

But I do not think we should discuss the automatic update issue now, because it will be automatically judged during the development. If the price of automatic update is very low, then we’ll have automatic update. If the price is too high, we’ll have manual or semi-automatic updates and if it’s somewhere in between, we’ll probably get a preferences option.

[TLS]

I have to agree with mikejt in that Framemaker's cross-referencing system is excellent and fast. Among its strengths:

1. it can function across more than one document so long as those documents are joined in a "book" file.

2. it is possible to build cross-reference "styles" using building blocks similiar to the Auto-title feature of Mellel. For example I have a c-r style that formats as "supra, pages #–#", one for "Plate #", one for "Document #: Auto-title text, page #", and another that is just "#". I build up just about anything that I please. Moreover, it is possible to assign character styles to everything so the numbers might be in a bold style while "supra" is in italic.

3. it is possible to search for broken c-r's.

4. updating c-r's will result in a pop-up box with links to any broken c-r's so they can be fixed

5. clicking on a c-r will give you the chance to go to the reference (even if in another file), but you don't have to

6. it is possible to see a marker for anything that is a c-r so these can be quickly visually located

While I seriously doubt Mellel with impliment Framemaker's system completely, it is certainly worth a look and is well-beyond that of MS Word's.

[Mats]

I am wondering, however, why it seems that obvious to so many that the CR should update when printing or saving and not immediately. If we cannot supply a decent speed with immediate updates of CRs we would not update immediately, of course, but why forfeit this in advance?

My opinion is that automatic updating uses processor power for a useless task.

A crossreference feature should be so user-friendly that it is extremely clear to the user which target he references to. If it works like that the reason for automatic updating of crossreferences is gone and merely something that is need to be done prior to printing. Actually, automatic updating should not - as I suggested in a previous post - be done when saving but only prior to printing - and at that stage through a confirmation box. Plus using a button in the tool area or menu area.

Also, imagine a 800 page document with 5 crossreferences on each page - not uncommon in STE typesetting - which means 4,000 crossreferences.

Best wishes,
Mats Broberg

[Ori Redler]

I agree with most of the stuff you wrote, but...

4. updating c-r's will result in a pop-up box with links to any broken c-r's so they can be fixed

Not with this one... Two reasons for that:
A. Sometimes you'd want to create a "blank" CR on purpose (e.g., referencing something you will write, but haven't so far.
B. There is a very significant "attrition factor" to such a dialogue and I think that a "nag" box should only be used when it is absolutely necessary (e.g., when something horrible might happen if you save/delete stuff).

[Ori Redler]

I am wondering, however, why it seems that obvious to so many that the CR should update when printing or saving and not immediately. If we cannot supply a decent speed with immediate updates of CRs we would not update immediately, of course, but why forfeit this in advance?

My opinion is that automatic updating uses processor power for a useless task.

A crossreference feature should be so user-friendly that it is extremely clear to the user which target he references to. If it works like that the reason for automatic updating of crossreferences is gone and merely something that is need to be done prior to printing. Actually, automatic updating should not - as I suggested in a previous post - be done when saving but only prior to printing - and at that stage through a confirmation box. Plus using a button in the tool area or menu area.

Also, imagine a 800 page document with 5 crossreferences on each page - not uncommon in STE typesetting - which means 4,000 crossreferences.

As someone mentioned above -- this is purely a question of if this can be done fast...

Ori

[verma]

As someone mentioned above -- this is purely a question of if this can be done fast...
Ori

Preferably, it should be "automatic" at least if it's for quite local references (I'm not sure I really need automatic updates of CRs that refer to main chapters or sections). If not possible for reasons of speed, it should still be as fast as possible. One could think of the "Print preview" approach used by some word processors (including LaTeX), but that's also time-consuming and a bit of a nag, frankly speaking.

If it can be done fast, go "automatic". I don't know if any trade-offs are needed to do it fast (like, limit updating to the main section the CR is in); if it can't be automatic, I'd vote for a procedure that avoids the "preview" approach and consider updating as a local procedure in a specific section, before a user-called general update is explicitly (non-automatic) asked.

[Normand]

I have a FrameMaker document of 616 pages with tons of figures, equations, tables, autotitles, subtitles...
This document contains more than 1500 cross-references.
I have purposely added a large part of everything at the beginning of the document to make sure that all CR will have to be updated.
Chronometer in hand, it takes less than a second to update the whole document (faster than the time to press the button ON-OFF of the chronometer). Let us say one second for 1500 CR.
It is with FrameMaker, an extremely good but old technology, on Classic, with a G4 PowerBook 867MHz, 768 Mo RAM.
I presume that with Mellel, a new and probably (hopefully) an extremely good technology too, with a DualCore at about 2GHz with 1Go RAM, it would not be a problem to automatically update CR, even for large document.
I must say that I performed one test on one document with one application (FrameMaker), then it is not a "scientific" result; it just give an idea...
Normand Beaudoin
Dept. of physics and astronomy
University of Moncton

[Ori Redler]

I have a FrameMaker document of 616 pages with tons of figures, equations, tables, autotitles, subtitles...
This document contains more than 1500 cross-references.
I have purposely added a large part of everything at the beginning of the document to make sure that all CR will have to be updated.
Chronometer in hand, it takes less than a second to update the whole document (faster than the time to press the button ON-OFF of the chronometer). Let us say one second for 1500 CR.
It is with FrameMaker, an extremely good but old technology, on Classic, with a G4 PowerBook 867MHz, 768 Mo RAM.
I presume that with Mellel, a new and probably (hopefully) an extremely good technology too, with a DualCore at about 2GHz with 1Go RAM, it would not be a problem to automatically update CR, even for large document.
I must say that I performed one test on one document with one application (FrameMaker), then it is not a "scientific" result; it just give an idea...
Normand Beaudoin
Dept. of physics and astronomy
University of Moncton

It is and it isn't an indication. Mellel is a WISIWYG word processor, so the there's more of an onus to keep things "live". FrameMaker, for the most part, is doing things first in a "sort of" fashion, and retrofits things later on -- that's a luxury we probably cannot afford.

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.

[Bill]

... Mellel is a WISIWYG word processor...

Very funny Ori!

[TLS]

Beyond the obvious, there are 2 features I would love to see in any cross-referencing system:

1. relative cross-references (this was mentioned before), so it is possible to have a CR that is "supra, pages #-#" or "infra, pages #-#" depending on the relative position of the marker.

2. conditional CR for single or multi-page references. For example if a CR refers to a short paragraph that falls on 2 pages it could read "see pages #-#" but if that paragraph fell on only a single page (due to repagination), the CR would reformat as "see page #". Both the page references and the word "page(s)" changed as needed. The ability to use "ff" (following folio/next page), as in "see page 26ff" (for "see pages 26-27") would be nice as well.

[nicka]

Maybe it's obvious -- and if so I apologise for bringing it up -- but one requirement is that very simple bits of text can be cross-references. So 'Section 3' without any 'above', 'below' etc. should be possible, and even more minimally, it should be possible to refer to a numbered example like this:
'See the sentence in (251):
(251) Mice cats dogs bite chase squeak.'
Here the text '(251)' in the first line would be the cross-reference, pointing to the numbered example. I mention this partly because you can't quite do this in Word -- only the number and the closing bracket are part of the cross-reference and the opening bracket has to be typed manually each time.