Post by amberv on Oct 23, 2005 22:18:58 GMT
A strong system for annotation is useful both in the writing process, and in the editing process. While writing, it should be a simple task to quickly insert a thought or two, and then resume typing where you were. This should be accomplished via the mouse or the keyboard, but neither exclusively.
When editing, it is important to have solid control over existing note and paragraph text. There shouldn't be a strong division between annotation and paragraph text. You could compare it to water surface tension. You can pass through surface to underwater very easily if you need to, but there is a very clear difference between above and below water. Notes and Text should be easily accessible between each other, but the line between them should be obvious. The Zen of software design.
There are various metaphors which have been adopted by the editing world. There are margin notes, which seek to emulate the process of jotting down thoughts in the blank spaces around a printed page. There are the so-called in-line notes, which are notes inserted directly into the text, and treated as text except for some colour, or symbol setting them apart. There are modal note "objects" inserted as icons into the text flow. There are annotation models where text is highlighted and then notes are added as meta-data to the text, or any other implementation of the "note database and pointer" method.
There are many systems, and I would like to propose the foundation to a system which combines some of the best aspects of other systems, and allows a writing platform to encapsulate them all into one, easy to use system, instead of having several different kinds -- or just one. To date, I only know of one application that has multiple methods of annotation and commentation, and many that have none, or very limited support for one method.
Before I began, we should address some common needs for annotations:
LyX is an X11 application, a front-end for LaTeX, which has an interesting solution to commentation. There are a lot of things I like about that editor, and one of them is how it handles footnotes, margin notes, and comments (for the most part).
It inserts a little button into the document, with the word 'note' written in it. When first created, the note is un-collapsed, and you can begin typing in it immediately. To leave the note, you just hit ESC, and the cursor returns to where you had been before adding it.
The way the note reacts to being in the document stream is modal. If it is collapsed, it will just look like a button, and you move around it just like you would any character in the page. When it is un-collapsed, you can see the contents of the note, and cursor movements will enter and leave it, in a natural way that you would expect. It is as if the contents of the note are in-line, at that point. I like this method because I can insert notes between paragraphs, or right inside the paragraph.
Another nice thing about LyX notes is that they can be selectively collapsed. I can have some remain open, and others closed. It remembers which way they were set between sessions. Alternatively, there is a menu command which will close all notes, or open them.
The Way They Look
Now, the way LyX does it is pretty ugly, visually speaking. Here are two examples of open and closed notes, which might be more Mac-like in their presentation.
Collapsed state
Un-collapsed state
See how note text flows right into paragraph text, albeit with a different colour. What this does is it allows you to drop portions of the paragraph with ease, and vice versa. You selected a sentence from your paragraph (or even several paragraphs from the page), hit Cmd-Shift-N (or whatever) and the contents of the selection get turned into a note; removed from the paragraph. A "note" tag gets inserted before it, and the colour of the text turns red.
The inverse should be possible, too. Select all or a portion of the note, hit Cmd-Shift-N, and the selected text gets dumped to the main document, after the note. This way you can promote and demote note from a text, easily.
Visually, you could alternatively use a background colour for the note, and leave the text black. It would allow the user to clearly see when the cursor has entered or left the note boundary at the end. If it is just coloured text on a white background, there could be some confusion. But, visually speaking, I like the "red" text better. For me that is distinctive enough, and yet subdued enough to not break the flow of the text -- to not become to visually intense. It looks "smart," for lack of a better term. You could have several hundred notes of this style in a document, without feeling overwhelmed. Another idea would be a smaller "end note" icon at the end. Perhaps just a round dot of the same colour as the icon, that would clearly be an in-note/out-note anchor. Another idea would be to have a thin outline drawn around the note text, in the colour (though of a subdued saturation to reduce "clutter") of the icon. This also would provide a clear boundary for the cursor to be in or out of.
An example idea
A word on colouring. I had the collapsed note in yellow, and the un-collapsed in red. I think the colour should be consistent -- I just went with two different ones to see how each would look. This could/should be a user selected preference, really. Yellow probably would not work so nice with text, though it looks nice as a button.
Editing with Notes
The note label is by default 'note,' (or whatever you prefer), but can be changed on a per-note basis. For example, I am typing, and I want to insert a note, so I press Cmd-Shift-N. A note icon is inserted at the cursor. At this point, I could just begin typing the note, and it would show up in the defined colour. Hitting ESC would end the note (and dump the cursor to the end of the note if I am editing inside of it). Alternatively, I could press Shift-Tab from anywhere in the note, and the text, 'note' in the icon would be selected. I could type in my custom tag at this point, and press Tab to get back to the note body. RWRI is my short-hand for "REWRITE", so I can quickly see what notes pertain to what. There could even be, say, five different colours of notes, since some people prefer colour to labelling. Auto-fill for previously typed in labels might be useful, here.
To collapse and un-collapse a note:
With the keyboard:
When advancing the cursor toward it, the note would be selected much like a button in Cocoa is selected, with a stroke drawn around (or within) the icon. If you were to press the right arrow again, it would go on to the text in the paragraph. If you were to press the spacebar while the note icon is selected, it would be un-collapsed. Tapping the spacebar again would collapse it. While un-collapsed, Opt-Right (or Left) would skip over the note, just as it skips over words, unless you are in the note text, then it would skip over words within the note, as one would expect.
With the mouse:
A simple click on the note icon would collapse/un-collapse the note, depending on its state. Double-clicking would edit the label. If collapsed, the label would be edited without un-collapsing the note.
Deleting notes should be as simple as deleting text. When collapsed, the note icon will act just like any other character on the page. If the cursor is right after it, and you press backspace, it will delete it. If it is selected and you press backspace (or delete), it will be deleted. They can be cut, copied and pasted just like ordinary text. The key is to treat them just as you would treat any text in the document stream.
As stated at the beginning, notes should have a tri-modal display model. You should be able to selectively display and hide notes depending on your work-flow. You should also be able to display all notes in the document, and likewise, collapse them all. However, I do not feel the icons should ever be hidden. Things would get too complicated if you are making editions to a document, without realising how much you are deleting, or if you are adding text to an area which will obscure the reference placement of an unseen note.
Referencing and Collecting Notes
So far, this has not addressed the concept of referencing, or pointing to a portion of existing text. I would suggest that the ability to place a note anywhere in the stream of text negates the need for a pointer, and that notes only need the ability to draw attention to their focus point if they are located in some area distant from the text itself. Such is the case with margin notes,paragraph constrained in-line notes, and their ilk.
Another nice feature would be the ability to collect all notes into a pseudo-page. The concept of pseudo-pages is something I have only seen done in one application, Circus Ponies Notebook. It collects diverse sundry of information into "index" pages. I think this is a powerful concept, and while probably overly ambitious at the moment. There are a lot of things to consider, such as how they should be displayed. Should notes from all documents be collected together, separated by headliners for document titles? Should there be a separate collection page for each document? At any rate, I can see this as being a useful feature in the long-term. Each note could be surrounded by a small amount of context from the surrounding document. Double clicking on a note would take you straight to that place in the document where it rests. I am not sure what the universal usefulness of this would be, though. I might use it from time to time, others, who use their notes for other things, might see a lot of benefit in it, and filtering the gathered collection by note type would be of obvious use, especially if you use a special note label for bibliographical information.
Portability and Exporting
Lastly, we come to portability. This is one of the stickiest issues with notes, because they are generally addenda to an already existing text format which does not support such addenda by itself. A text-only document has no convention for meta-data added to it. Even RTFs have very limited features in this area. It is obvious to me that the best system for notation in this case would be one where the visual representation of notes is only a metaphor for an underlying, purely textual system, which is ultimately portable to any environment. For instance, say the above graphical system were implemented. If you were to open the Scrivener file in BBEdit, what you would actually see is:
Using this system, the outer brackets define the limits of the note. The inner brackets define the label. The plus sign at the beginning denotes that this note is collapsed. An un-collapsed note would look like ...{-{RWRI}There...
Obviously, this is just an example, and whatever system was employed, it would have to be sufficiently arcane so as to not accidentally invoke it through normal usage -- while remaining easy to read in any other program.
These notes would be physically expressed this way on every level except the visual, in Scrivener. If you were to copy the buffer and paste it into TextEdit, you would see the notes similar to the above example. There could be an optional thing in the edit menu that says Copy Without Notes. Or perhaps the inverse behaviour would be better?
Onward...
There could perhaps be other systems employed once the basic set-up exists. How about telling the export engine to export all notes with a certain label as footnotes, and ignore the rest? It could automatically enumerate them, and collect them text of the notes to the bottom of the document (or whatever method the export format requires). But, like extensive note collection systems and pseudo-page collection, these are all topics for another day.
When editing, it is important to have solid control over existing note and paragraph text. There shouldn't be a strong division between annotation and paragraph text. You could compare it to water surface tension. You can pass through surface to underwater very easily if you need to, but there is a very clear difference between above and below water. Notes and Text should be easily accessible between each other, but the line between them should be obvious. The Zen of software design.
There are various metaphors which have been adopted by the editing world. There are margin notes, which seek to emulate the process of jotting down thoughts in the blank spaces around a printed page. There are the so-called in-line notes, which are notes inserted directly into the text, and treated as text except for some colour, or symbol setting them apart. There are modal note "objects" inserted as icons into the text flow. There are annotation models where text is highlighted and then notes are added as meta-data to the text, or any other implementation of the "note database and pointer" method.
There are many systems, and I would like to propose the foundation to a system which combines some of the best aspects of other systems, and allows a writing platform to encapsulate them all into one, easy to use system, instead of having several different kinds -- or just one. To date, I only know of one application that has multiple methods of annotation and commentation, and many that have none, or very limited support for one method.
Before I began, we should address some common needs for annotations:
- It should be very simple to start and end typing in a note. When in the process of typing, the mouse should never be required. When editing, the keyboard should not be required (until you start typing the note contents, obviously).
- Notes often need a pointer, or a reference in the base text; adding and removing them should be simple.
- It should be simple to display every note, or none at all.
- Notes should be selectively displayed or hidden, and this system should be independent from the above system (tri-modal, where selective display is persistent, behind all/none modes).
- They should be portable, easy to export.
LyX is an X11 application, a front-end for LaTeX, which has an interesting solution to commentation. There are a lot of things I like about that editor, and one of them is how it handles footnotes, margin notes, and comments (for the most part).
It inserts a little button into the document, with the word 'note' written in it. When first created, the note is un-collapsed, and you can begin typing in it immediately. To leave the note, you just hit ESC, and the cursor returns to where you had been before adding it.
The way the note reacts to being in the document stream is modal. If it is collapsed, it will just look like a button, and you move around it just like you would any character in the page. When it is un-collapsed, you can see the contents of the note, and cursor movements will enter and leave it, in a natural way that you would expect. It is as if the contents of the note are in-line, at that point. I like this method because I can insert notes between paragraphs, or right inside the paragraph.
Another nice thing about LyX notes is that they can be selectively collapsed. I can have some remain open, and others closed. It remembers which way they were set between sessions. Alternatively, there is a menu command which will close all notes, or open them.
The Way They Look
Now, the way LyX does it is pretty ugly, visually speaking. Here are two examples of open and closed notes, which might be more Mac-like in their presentation.
Collapsed state
Un-collapsed state
See how note text flows right into paragraph text, albeit with a different colour. What this does is it allows you to drop portions of the paragraph with ease, and vice versa. You selected a sentence from your paragraph (or even several paragraphs from the page), hit Cmd-Shift-N (or whatever) and the contents of the selection get turned into a note; removed from the paragraph. A "note" tag gets inserted before it, and the colour of the text turns red.
The inverse should be possible, too. Select all or a portion of the note, hit Cmd-Shift-N, and the selected text gets dumped to the main document, after the note. This way you can promote and demote note from a text, easily.
Visually, you could alternatively use a background colour for the note, and leave the text black. It would allow the user to clearly see when the cursor has entered or left the note boundary at the end. If it is just coloured text on a white background, there could be some confusion. But, visually speaking, I like the "red" text better. For me that is distinctive enough, and yet subdued enough to not break the flow of the text -- to not become to visually intense. It looks "smart," for lack of a better term. You could have several hundred notes of this style in a document, without feeling overwhelmed. Another idea would be a smaller "end note" icon at the end. Perhaps just a round dot of the same colour as the icon, that would clearly be an in-note/out-note anchor. Another idea would be to have a thin outline drawn around the note text, in the colour (though of a subdued saturation to reduce "clutter") of the icon. This also would provide a clear boundary for the cursor to be in or out of.
An example idea
A word on colouring. I had the collapsed note in yellow, and the un-collapsed in red. I think the colour should be consistent -- I just went with two different ones to see how each would look. This could/should be a user selected preference, really. Yellow probably would not work so nice with text, though it looks nice as a button.
Editing with Notes
The note label is by default 'note,' (or whatever you prefer), but can be changed on a per-note basis. For example, I am typing, and I want to insert a note, so I press Cmd-Shift-N. A note icon is inserted at the cursor. At this point, I could just begin typing the note, and it would show up in the defined colour. Hitting ESC would end the note (and dump the cursor to the end of the note if I am editing inside of it). Alternatively, I could press Shift-Tab from anywhere in the note, and the text, 'note' in the icon would be selected. I could type in my custom tag at this point, and press Tab to get back to the note body. RWRI is my short-hand for "REWRITE", so I can quickly see what notes pertain to what. There could even be, say, five different colours of notes, since some people prefer colour to labelling. Auto-fill for previously typed in labels might be useful, here.
To collapse and un-collapse a note:
With the keyboard:
When advancing the cursor toward it, the note would be selected much like a button in Cocoa is selected, with a stroke drawn around (or within) the icon. If you were to press the right arrow again, it would go on to the text in the paragraph. If you were to press the spacebar while the note icon is selected, it would be un-collapsed. Tapping the spacebar again would collapse it. While un-collapsed, Opt-Right (or Left) would skip over the note, just as it skips over words, unless you are in the note text, then it would skip over words within the note, as one would expect.
With the mouse:
A simple click on the note icon would collapse/un-collapse the note, depending on its state. Double-clicking would edit the label. If collapsed, the label would be edited without un-collapsing the note.
Deleting notes should be as simple as deleting text. When collapsed, the note icon will act just like any other character on the page. If the cursor is right after it, and you press backspace, it will delete it. If it is selected and you press backspace (or delete), it will be deleted. They can be cut, copied and pasted just like ordinary text. The key is to treat them just as you would treat any text in the document stream.
As stated at the beginning, notes should have a tri-modal display model. You should be able to selectively display and hide notes depending on your work-flow. You should also be able to display all notes in the document, and likewise, collapse them all. However, I do not feel the icons should ever be hidden. Things would get too complicated if you are making editions to a document, without realising how much you are deleting, or if you are adding text to an area which will obscure the reference placement of an unseen note.
Referencing and Collecting Notes
So far, this has not addressed the concept of referencing, or pointing to a portion of existing text. I would suggest that the ability to place a note anywhere in the stream of text negates the need for a pointer, and that notes only need the ability to draw attention to their focus point if they are located in some area distant from the text itself. Such is the case with margin notes,paragraph constrained in-line notes, and their ilk.
Another nice feature would be the ability to collect all notes into a pseudo-page. The concept of pseudo-pages is something I have only seen done in one application, Circus Ponies Notebook. It collects diverse sundry of information into "index" pages. I think this is a powerful concept, and while probably overly ambitious at the moment. There are a lot of things to consider, such as how they should be displayed. Should notes from all documents be collected together, separated by headliners for document titles? Should there be a separate collection page for each document? At any rate, I can see this as being a useful feature in the long-term. Each note could be surrounded by a small amount of context from the surrounding document. Double clicking on a note would take you straight to that place in the document where it rests. I am not sure what the universal usefulness of this would be, though. I might use it from time to time, others, who use their notes for other things, might see a lot of benefit in it, and filtering the gathered collection by note type would be of obvious use, especially if you use a special note label for bibliographical information.
Portability and Exporting
Lastly, we come to portability. This is one of the stickiest issues with notes, because they are generally addenda to an already existing text format which does not support such addenda by itself. A text-only document has no convention for meta-data added to it. Even RTFs have very limited features in this area. It is obvious to me that the best system for notation in this case would be one where the visual representation of notes is only a metaphor for an underlying, purely textual system, which is ultimately portable to any environment. For instance, say the above graphical system were implemented. If you were to open the Scrivener file in BBEdit, what you would actually see is:
...revealing cold pockets of yellowed dusk; {+{RWRI}There is something about this paragraph which unsettles me, and perhaps that is what you were going for when you originally sat down and wrote it.} felt this was not a thought...Using this system, the outer brackets define the limits of the note. The inner brackets define the label. The plus sign at the beginning denotes that this note is collapsed. An un-collapsed note would look like ...{-{RWRI}There...
Obviously, this is just an example, and whatever system was employed, it would have to be sufficiently arcane so as to not accidentally invoke it through normal usage -- while remaining easy to read in any other program.
These notes would be physically expressed this way on every level except the visual, in Scrivener. If you were to copy the buffer and paste it into TextEdit, you would see the notes similar to the above example. There could be an optional thing in the edit menu that says Copy Without Notes. Or perhaps the inverse behaviour would be better?
Onward...
There could perhaps be other systems employed once the basic set-up exists. How about telling the export engine to export all notes with a certain label as footnotes, and ignore the rest? It could automatically enumerate them, and collect them text of the notes to the bottom of the document (or whatever method the export format requires). But, like extensive note collection systems and pseudo-page collection, these are all topics for another day.
