Page 1 of 7

[Discussion] Cross referencing

Posted: Fri Sep 29, 2006 2:59 am
by Ori Redler
Cross referencing is coming soon to Mellel, and now is a good time to start discussing some of the details.

What is Cross Referencing
Cross referencing is the ability to point (or refer) from one place in your document to another place in your document. For example, you may be writing on page 6 about a figure displayed on page 3. With cross referencing, you can simply refer to this figure by entering a reference (e.g. "see figure on pay 3").

You can do that manually, of course, but if you add anything that changes the numbering of the figures or pages, you have to go over your references and correct them, one-by-one. Such manual updating can be very time consuming, and the end result will probably contain some errors.

Cross referencing eliminate this hassle by allowing you to refer to a selected place in the text, and have the reference change dynamically when the document text changes.

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.

In an application like MS word, this is done in the following manner:
1) You choose to insert a Cross Reference.
2) You choose to what you wish to refer to. You can refer to headings, tags (like figures) bookmarks and notes.
3) You choose what aspect of the thing you refer to (e.g., a footnote's number, a heading's text, a bookmark's page number) you wish to refer to.

And we have all three: the referrer, the referred, and the mechanism to connect them.

Limitations
All this works, of course, but is rather crude and imprecise. One can point to several limitations:
One at a time: When you refer to something, you can only refer to one element of it at a time (e.g., "see figure 2") and have to add several cross references in a row to get what you want (e.g. "see figure, under chapter 1 on page 34").
Introductory text: many people want to have the same introductory text all the time (e.g. "see also X" but never "also see X"). As you need to add the introductory text manually, there is a problem maintaining consistency.
Cleanliness: You have to work very cleanly with stuff. If you split or cut or move something you've referred to, the app. gets confused to what it needs to refer in the cross reference. This can get rather messy.
No automatic-updating: You have to initiate the updating every time.
Re-Editing: it is not easy to get into editing a cross reference. You need to select it and than choose Insert > Cross Reference... which is somewhat counter-intuitive.
Limited selection: There is no option to easily point to text in the document, a position in the document, to nowhere, and so on.

What needs to be done
This is where you come in...

Cross reference attribute

Posted: Fri Sep 29, 2006 4:51 am
by Bill
Here is a feature request for a cross referencing attribute:

When references are imported from reference software [1], it would be neat if the reference numbers and related endnotes pointed to each other. (i.e. Click on the reference number and you're taken to the corresponding endnote, and vice versa.)


[1] Bookends or Sente

Re: Cross referencing

Posted: Fri Sep 29, 2006 7:10 am
by fitzgunnar
Wonderful that this feature is coming near! In my 370 pages dissertation I make references to different parts of the book all the time, and it has been a pain not to have any automatic cross references. (It would have been great to have the feature earlier...)

To answer Ori:

1. I think Word's system is ok. As long as you refer to already numbered items, it is simple enough. However, the use of bookmarks to refer to free text on some page takes a while to a) understand and b) find a "clean" way of working with. (After some 20 bookmarks it gets a bit tricky to know which bookmark name refers to which text.)

By placing this comment at the top of my list I want to point out that even Word's simple system is much, much better than no system at all. Do not wait with implementing this feature just because it is no better than Word's implementation! Implement, and the revise if you find a better way to do it.

2. Having "introductory texts" and multiple cross references seem like something that won't be used anyway. Sure, I often make references that look the same, but I often need some special twist to it. It is much easier to edit the details of the reference immediately than setting up some kind of general template for it.

3. Automatic updating: possibly the worst part of Word's system. Automatic updates is the whole idea of automatic cross references! If it is time consuming and difficult, than add warnings or triggers each time the user saves or prints the document.

4. Cleanliness: I guess some kind of warning system is needed, so that broken references are pointed out for the user. Silently removing them (which is a theoretical option) is hardly a good idea.

5. Re-editing: I do not see the big use. Just delete the cross reference and insert it again.

6. Limited selection: I guess this is where Word uses bookmarks. It is a system that works, but it feels like you do things "backwards": first make a bookmark, and the refer to it. An alternative way could perhaps be something like this:
  1. Start inserting a cross-reference
  2. Select "free text" as a reference type
  3. Mellel then instructs the user to select the text that is to be referred to. One way of doing this could be to dim the entire text, and let the user "drag" a clear section. (Like it is done in iPhoto with red eyes. Hm, at least it was done like that in iPhoto 2...)
This would probably be more intuitive, but it you refer to the same piece of text several times, it has to be pointed out several times too. But I suspect that parts that you often refer to also have their own numbers (sections, figure numbers, etc).

That was my thoughts on the subject. Cheers,

MagnusG!

Posted: Fri Sep 29, 2006 7:56 am
by kabouter
Excellent, Ori. I've been impatient for cross referencing for ages.

One thought occurred to me: if I have a cross reference to a section in my text but then later delete that section could there be some sort of alert in place? Maybe this would work best when updating is initiated – a window could pop up showing places where a reference is missing so that it would be possible to select each one and edit as needed.

Or maybe you've thought of this and I've misunderstood.

Posted: Fri Sep 29, 2006 4:03 pm
by redlers
kabouter wrote:Excellent, Ori. I've been impatient for cross referencing for ages.

One thought occurred to me: if I have a cross reference to a section in my text but then later delete that section could there be some sort of alert in place? Maybe this would work best when updating is initiated – a window could pop up showing places where a reference is missing so that it would be possible to select each one and edit as needed.

Or maybe you've thought of this and I've misunderstood.
As a general comment -- don't "think Word" -- since we're discussing this with view to implementing this on our own, there's no need to refer to MS Word's limitations as something that would necessarily limit our implementation as well. Updating can and should occur while you write, and not by special request.

Regarding a reference to something that does not exist anymore -- the best solution, it seems to me, is not a warning (which is time consuming and can be a real nag if you have 30 of those) but a way to browse all "orphan" references and "solve" or delete them.

Posted: Fri Sep 29, 2006 8:32 pm
by digimarkus
redlers wrote: Regarding a reference to something that does not exist anymore -- the best solution, it seems to me, is not a warning (which is time consuming and can be a real nag if you have 30 of those) but a way to browse all "orphan" references and "solve" or delete them.
I would prefer this sort of option. You might consider prompting the user when opening/closing a document that the document contains x number of broken links. However, even this can be annoying. So long as there is a place to "report" on the number of broken links (i.e. Document Statics), that's all I need.

Posted: Sat Sep 30, 2006 3:40 am
by kabouter
redlers wrote:As a general comment -- don't "think Word" -- since we're discussing this with view to implementing this on our own, there's no need to refer to MS Word's limitations as something that would necessarily limit our implementation as well. Updating can and should occur while you write, and not by special request.
Ok, I did misunderstand then. I thought you meant there would not be automatic updating in Mellel.
redlers wrote:Regarding a reference to something that does not exist anymore -- the best solution, it seems to me, is not a warning (which is time consuming and can be a real nag if you have 30 of those) but a way to browse all "orphan" references and "solve" or delete them.
That makes sense. As long as there is some way to track down the "orphans" and edit each one I'm happy - in some cases deleting the reference may be enough, but in other cases more text may need to be added.

Posted: Sat Sep 30, 2006 7:33 am
by simifilm
Something I'd like to see: References to page ranges. Probably not too difficult to do, but I'd like to see something along this line:

- Reference-In point,
- Reference-Out point
- Depending on the range a reference which is in the form of 21 f. or 21-27.

simon

Cross Indexing

Posted: Sat Sep 30, 2006 9:21 pm
by laup
I agree with the sentiment that something is much better than nothing, and that something pretty good and simple is far, far better than nothing at all.

I worry that this and other sophisticated featues will affect software quality. Anything that requires Microsoft-like macros is exceedingly dangerous because it introduces version depenence, portability problems, and the potential for an OS update to break things badly. I am probably too much affected by experiences with macros in Microsoft Office applicatons, but I would think that an architectually clean alternative would be desirable. Tags would presumably be objects with a rather substantial set of attributes and those attributes would be cross-llinked.

On a positive note, Bookends has to plow some of the same ground and seems to do so pretty well. My impression, however, is that updates are needed every time OS X is updated by 0.1.

Posted: Sun Oct 01, 2006 1:08 am
by Ori Redler
A summery of sorts:

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.

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.

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.

Updating
Should be immediate, in my view.

Some Specifics

Posted: Sun Oct 01, 2006 4:20 am
by Bill
Ori provides an excellent summary of general features that that would be nice to see in a cross referencing system.

I'd like to touch on a few slightly more specific aspects that I hope will be implemented at some point. My comments are based on my own notion that the behavior of a cross referencing system may be dependent upon the type of item being referred to - auto-title, arbitrary item, object, etc.

First, I'd like to clarify my prior post with repect to objects imported from reference software such as Bookends. It would be great if the imported reference numbers in the text and in the endnotes were cross referenced automatically - no (or minimal) user intervention required.

Second, with repect to auto-titles, here is an example of what I need to do for a particular journal:

Figure captions must contain the full word "Figure", while referring text must use the abbreviation "Fig." So, my text might have a comment like "as indicated in Fig. 2 ...", while the Figure caption is "Figure 2". I'd like to be able to click anywhere on the term Fig. 2, and be taken to Figure 2.

The interesting thing about auto-titles is that the user doesn't have access to the auto-title numbers. If that's still the case in future releases, then the software must be able to grab the auto-title number from the "referred to" auto-title item and place it just after the referring text (i.e. just after Fig. ).

Third, it seems to me that in some cases, cross references should be two-way, while in other instances, they should be one-way. For example, it makes sense for specific items such as reference numbers in text and in endnotes to function in both directions. However, perhaps references from specific text to more general items such as headings or pages should be one-way.

If cross references are one-way, then perhaps some sort of navigation sytem, such as a back button, is needed to get back to the original referring item.

Posted: Sun Oct 01, 2006 12:30 pm
by Reiner
most here sounds very good, i just want to highligth that is is very important imho that there is a good way to manage huge amounts of references, a kind of browser or something would be good.

a few more addtions:

if you want to refer to a chapter, part ... easiest to insert a reference would be the context-menu in the outliner "add cross-reference"

i think it should not only be possible to use cross-refs as links within the document, later the links should also work in pdfs you made from your mellel-documents.

i would like to add column numbers, margin-numbers, index- and toc-names as targets of references (which are themselves implicit feature requests of course).

how about cross-references to second Mellel-files?

Posted: Sun Oct 01, 2006 8:40 pm
by kabouter
For the sake of user-friendliness, I would prefer to have a separate window from which to select the item to be referenced.

I use the outline a lot for naviagation, but many of my titles are long and my monitor small so I can't see the full outline and full page I'm working on at the same time. This would make it hard to drag a title over to the right place in the text for referencing puposes.

I would prefer a separate window (a palette would be fine provided I can resize it to read an entire title). I could then click the title then drag and drop it to correct location in the text. I think this would be easier and faster than having to use an insert menu.

Granted, I'm thinking in terms of references to section headings, tables, figures, etc. which is what I see using most.

I also would like the option of defining auto text for references. Maybe this could best be set up in the auto-titles settings, where the user could choose how referenced items appear in the text. (Same idea as for mentions.) This might be good for people who want multiple references for an item, e.g., Table 1 in Chapter 2. The user could define table 1 and somehow tell Mellel to include not only the table number but to automatically add chapter, section, page number(s), or whatever else. The user then only has to add a cross reference in the text for Table 1 and Mellel automatically adds all other info. (Instead of the user having to cross reference each piece of info, i.e., table and chapter, or table and page numbers.)

Hope I'm making sense today.

Also, I agree with Reiner's suggestion for cross-referencing appearing as links, especially in .pdfs. I've thought of (and wanted) that too.

Posted: Mon Oct 02, 2006 5:32 pm
by Mats
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

Posted: Tue Oct 03, 2006 2:11 am
by Danoz
I completely agree with Mats. The ability to add contextual text like, "above", "below", "facing" etc is important.

I also support the notion of two way navigation. I would like to be able to select some text and see (e.g. in a palette or the browser) what are the links to this text (or object) and what are links from this text. Selecting and then clicking view/go to would then jump you to that location.

Like some others, I also think that this would be improved with some additional new Mellel features, like "View/Go to CR in new Window" and "View/Go to CR in new pane" ie for split window views.

Nick