Annotations
From AbiWiki
| Line 1: | Line 1: | ||
| - | + | = AbiWord Annotations = | |
The project started and we are trying to get some [[#FeedBack][feedback]] to enrich the proposal. | The project started and we are trying to get some [[#FeedBack][feedback]] to enrich the proposal. | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
= Introduction = | = Introduction = | ||
Revision as of 13:46, 27 November 2010
Contents |
AbiWord Annotations
The project started and we are trying to get some [[#FeedBack][feedback]] to enrich the proposal.
Introduction
This project would implement a "comment" feature, which enables users to place comments over regions of text which are visible on screen but do not actually in terfere with the document and are invisible when printed. (Original proposal)
The project is part [[1][Google Summer of Code '07]] p rogram chosen from a list of proposed [[SummerOfCode2007][Abi projects]]. The pr oject will be made by [[Main.MartinSevior][Martin Sevior]] (mentor/supervisor) a nd [[Main.RiveraE][Ernesto Rivera]] (selected student).
Some links of interest to start with.
- [Abiword Overview]
- The PieceTable
- http://www.abisource.com/doxygen/
Goals
Provide a complete solution to work with annotations in <nop>AbiWord:
- Annotations will be both user-created (as in MS Word) or automatically created by <nop>AbiWord (ex. revision marks and their comments). Users will be able to show/hide them according to the annotation type.
- They will also be easy to print for drafts, and easy to hide for distribution.
- They will be implemented in a clean and extensible way, as it is an important feature over which other developers will certainly work.
- If feasible within the 3-4 months period, annotations will be able to accommodate rich text and objects as pictures that AbiWord handles.
Approach
Annotations are being implemented cooperatively between [[Main.MartinSevior][Martin Sevior]] and [[Main.RiveraE][Ernesto Rivera]].
In principle, Martin will take care of the bases (working with the PieceTable) and Ernesto with the GUI and functionalities.
First goal
Mean to be implemented *fast*.
- Allow users to add _punctual_ annotations in line with text. Punctual means that annotations at first won't span throw text or other objects, thus ensuring the annotation will be contained on a single Piece object. New menu items:
- Insert -> Annotation
- Place visual queues where annotations exist (either an small graphic o
r small character as implemented on footnotes).
- Allow users to show, hide, create, edit and delete comments:
- Show: tooltip on mouseover (alternatively for touchscreen users let us
ers show tooltip by clicking on its icon).
- Hide: unfocus the mouse (touchscreen users click again on the icon or
click somewhere else).
- Create: Place the annotations icon at cursor position and activate edi
t as described in the next point.
- Edit: simple dialog with a text field.
- Delete: delete just like text or image (ex. backspace).
Second goal
First refinements.
- Create an unifying annotations view (most likely a drawer cf. competing produc
ts).
- Allow printing of comments.
- Menu (and possibly toolbar) modifications:
- Create an Annotations submenu, move there Add annotation along with the new menu items below.
- Show/hide visual annotations queues (icons).
- Show/hide annotations drawer.
- Delete all annotations
Schedule
_From SoC proposal_
In order to provide a complete solution (a working version) some trade-offs will have to be made for the first version, mostly at the graphical level and flexibility. Limiting those aspects will ensure that more important tasks will be completed in the 3-4 months timeframe. In this regard, the most important tasks to accomplish during the summer are to allow: editing, printing and saving annotations using <nop>AbiWord's file format
- Get used to AbiWord code. Survey annotation implementations in competing produ
cts (both commercial and open source ones).
- Study somewhat similar features: footnotes and revisions. Polish this schedul
e and fully decide/prioritize/detail the following tasks. (interim period, April 6 - May 28).
- Define the best way to store annotations inside the *.abw file format (this af
ter studying open file format implementations).
- Study the state of cooperative initiatives in AW for the future: annotations c
ould play an important role in multi-user edited documents. (2 weeks).
- Implement basic annotation functionality (2 weeks):
- Create annotation menus.
- Select some text and mark it as an annotation.
- Change its appearance (text color/font, make it italic, etc.) as in revisions.
- Ensure that saving and opening files preserves annotations.
- Allow to hide/show user annotations along with AbiWord-generated annotations (1 week)
- Allow to print annotations (1-2 weeks).
- Allow to selectively show/hide certain annotation types (1 week).
- Make annotations more user-friendly (2-4 weeks, depending on the level of friendless targeted for the first release):
- Create contextual menus to allow creating annotations from selected text and insert annotations anywhere.
- Create an annotation toolbar complete with icons (could be combined with a much needed toolbar for revisions).
- Display annotations outside regular text leaving only a mark behind (like footnotes) or arrows (like MS Word).
- Allow rich text annotations and insertion of just any object AbiWord can handle.
- Fix bugs and quirks (1-2 weeks).
- Document everything (1 week).
Further development
Allow importing and exporting of annotations from/to some common text file formats.
Project status
- The <nop>SoC program officially started on May 28th.
Competing products
_Images hosted on an external server_
Microsoft Word
Microsoft Word has a combined revision control/annotations mechanism.
'Creating comments'
New annotations are/can be created:
- User created annotations.
- Automatically if user activates the "track changes" functionality. In case multiple users work on a same file modifications made by each user will be shown using a different color.
- Audio annotations.
'GUI'
- Displayed besides main text with arrows pointing to the insertion place of the document.
- Displayed in a _drawer_ below the document window along with all changes, headers and footnotes.
- Hidden/shown by type.
- Printed or not.
'Screenshots'
_Word 2004 OSX_
- Comments displayed beside text (this view can be printed).
http://two.xthost.info/abi/wordcomment1.png
- Comments displayed in a separate drawer (this view can not be printed).
http://two.xthost.info/abi/wordcomment2.png
- There exist also audio annotations, and while audio is out of our scope, their presence mark is quite unintrusive.
http://two.xthost.info/abi/wordcomment3.png
- Finally the only way to print comments as said is displaying them beside text which compresses text to the left even for pages without comments...
http://two.xthost.info/abi/wordcomment4.png http://two.xthost.info/abi/wordcomment5.png
Adobe Acrobat Professional (CS3)
By far the Acrobat implementation is both more complete and more cluttered than Word's solution.
'Creating comments'
- As with Word, here users can choose to create revision/edditing comments *automatically* as they work. In case we envisage to allow users to keep track of changes this kind of mechanism may be a good option.
http://two.xthost.info/abi/acrobat4.png
- Users can also create stickies and several other "comment objects" manually, which can also be confusing as show below.
'GUI: Annotations within text'
This is how it looks when you start using comments.
- Start with a few simple comments associated to text segments. The little icon that appears where a comment start is the kind of small unintrusive icon I think should be used for Abi. However the extra colouring could be avoided, or only shown when the mouse hovers over the icon (and then possibly also popping-up the comment contents).
http://two.xthost.info/abi/acrobat1.png
- Then add some "stickies" positioned on the document independently of the text.
http://two.xthost.info/abi/acrobat2.png
- And if you really want add some "stamps", arrows, bubbles, clouds and more.
http://two.xthost.info/abi/acrobat3.png
'GUI: Handling comments'
- Showing and hiding comments as well as their (far too) many options (the arrows lead to some extra ones).
http://two.xthost.info/abi/acrobat6.png
- Once again the comments drawer is the easiest way to work with comments while clicking on them jumps to the text area associated with it.
http://two.xthost.info/abi/acrobat7.png
'Printing'
- For printing one more lots of options are available.
http://two.xthost.info/abi/acrobat8.png
The most useful for me is the default one which will print the text just "normally" while inserting extra pages after pages with comments.
Feedback
Ideas and comments here please.
- 2007/06/07, Martin Sevior:*
My current favourite implementation is to place comments at the bottom of the page like footnotes with the option of pop-ups during a mouse-over or right click. We can hide the comments at the bottom of the page via a menu option or print them out as the user wishes.
I like this approach because it will allow comments to be both printed or hidden entirely. It allows comments to be as verbose as the author likes without cluttering up the document too much. The pop-up allows users to see the comments directly against the text. It also has the virtue of being relatively easy to implement as we can reuse much of the footnote code which has been almost fully debugged (at much pain I have to say!).
It also doesn't mess with margins so this approach can be directly used by OLPC Write.
- 2007/06/05, Tomas Frydrych:*
_Possibilities for displaying a comment are:_ _1. Box in the margin with the comment._
If there are more than few and/or the comments are not very brief, this would screw the layout beyond recognition. I am not sure this can be made to work in practice very well (at all).
_2. A popup that appears during a mouse-over._
I like the pop up for on-screen use, but please be aware that mouse-over events assume a mouse, and hence do not work on devices that have a touch screen. It needs to be possible to pop the annotations by a press event, and it also needs to be possible to place the caret at a document position which happens to have annotation using a press, i.e., there needs to be spatial offset between the annotation mark and the document position.
_3. make the text appear inline with a defined format. This should be hidable._
I do not particularly like this. In the past, I have often annotated my documents with inline comments and they severely disrupt the flow of the original text, often being more trouble than they are worth. At the same time, this would be relatively simple (it's like text which has hidden markup), and it would work printing-wise.
There is also the option to have the annotation comments in a separate container, either at the bottom of each page like footnotes, or at the end of the document like endnotes. For printing, I think I would prefer this to both the margin and inline options.
- 2007/06/05, Ryan Pavlik:*
Also, it might be a good idea to make sure you don't re-invent the wheel by including re visions support in Annotations: Play around with the existing revisions support and see
how it can be worked with to further your project.
- 2007/06/05, Robert Staudinger:*
First of all, I would recommend against putting revision information in the annotations.
Also have you ever worked with a heavily revised document in MsWord? The "bubbles" appr
oach used just doesn't scale good enough. (For revisions I'd recommend a vertical split view, but that's another thing ...)
Secondly I think conceptually two approaches to annotations can be distinguished:
- Annotations to "insertion points" (arbitrary locations in the document, like footnotes)
- Annotations to "objects" (sections, headlines, paragraphs, images ...)
I think the "annotations to objects" approach is preferrable, because it adheres more to
the document structure and allows for better rendering. What is meant by that?
Imagine a snippet of text that contains 3 annotations. The annotation rendering code wou ld have to figure out how to smartly place the "bubbles" displaying them, because they a re unrelated to each other.
On the other hand, if you attach annotations to the paragraph they are contained in, it should be rather straight forward to render a single bubble that contains all 3 annotati ons. For finer granularity, e.g. to make it clear which span belongs to a particular ann otation the span in question can be highlighted when clicked or hovered.
A ridiculously simple mockup for illustration: http://abisource.com/~robsta/mockups/annotations.png
The mockup also shows an inline view that displays annotation below their associated obj ects, similar to a blockquote, which might be preferrable for printing. Additional decor ations can of course be added to make clear it's an annotation. (If the bubble/inline vi ew mode for annotations could be switched on a per-object basis then inline annotations could also be used to add captions to images, tables ...)
- 2007/06/04, Leonard Rosenthol:*
(...) A couple of things that strike me offhand.
- You need at least 4 types of "annotations" - popup note (a non-anchored/floati
ng note), hilite ("yellow" hilite marker), strikeout and insertion. These are the most common types of operations performed. You could also do a specific "replacement", but t hat can be simulated just fine with a combination of strikeout + insertion.
- Each annotation type MUST allow for associated descriptive text to explain why
the operation was performed or the text in question (for popups & insertions).
- I see an annotation similar to a hyperlink, so perhaps the same/simiar mechani
sm used in the PieceTable for defining links should be used?
- 2007/06/04, Martin Sevior*
(...) A minimum first goal for the project will be:
- Allow selected regions of the text to have a comment associated with them.
- Define a standard way to display that a region has a comment associated with it.
- Make displaying the comment user-definable and potentially printable.
Possibilities for displaying a comment are:
- Box in the margin with the comment.
- A popup that appears during a mouse-over.
- make the text appear inline with a defined format. This should be hidable.
Regarding implementation, I agree that annotations should be represented in the piecetab le in a way similar to footnotes. However we will need to combine this with the mechani sm we use for hyperlinks to show which region of the text is associated with a comment.
If we use the footnote mechanism to hold the comment in the piecteable, the easiest method to display the comment is either the popup box or a comment in the margin. Putting comments in the margin is also a straight forward way to allow printing.If we pursue this path we will have to expand the size of the left margin in OLPC Write.
_Side note_ Building AbiWord 2.5.1 for Apple's X11
_This should be moved to a new article_
Experience installing AbiWord from the SVN trunk and compiling it on a iMac G5 (so PPC) on Mac OS X 10.4.10 using Apple's X11 implementations.
- Install [[2][Apple Developer Tools]] (XCode 2.4.1) a
nd make sure to install X11's SDK as well. Free registration required.
- Install [[3][MacPorts]] (formerly known as <nop>DarwinP
orts). With it you can do several things to get ready to build AbiWord:
- Fast but not recommended: install abiword-x11 using the port command.
It will install required libraries and take care of dependencies while installing a usab le AbiWord on =/opt/local/bin=. However it will be an outdated AbiWord, and potentially no longer needed or even worse conflicting libraries along.
- Better: Install manually (=sudo port install xxxx=) the required libra
ries as listed on port's _Portfile_ located at =/opt/local/var/db/dports/sources/rsync.r sync.darwinports.org_dpupdate_dports/editors/abiword-x11=. In my case: <verbatim>depends_lib �
port:gnome-platform-suite �
port:zlib �
port:fribidi �
port:fontconfig �
port:libgnomeprintui</verbatim>
- Best: Try to compile compile AbiWord and install packages as errors an
d warnings appear.
- Flags:
- The Portfile suggests:
configure.args �
--disable-Cocoa �
--disable-Carbon �
--mandir=${prefix}/share/man �
--without-epath �
--enable-gnome</verbatim>
- These compile but crash on launch:
./autogen.sh --disable-Cocoa --disable-Carbon --without-epath --disable-gnome --disable-bonobo --with-darwinports --enable-debug ./autogen.sh --disable-Cocoa --disable-Carbon --enable-debug --with-darwinports
- Worked for me:
<verbatim>./autogen.sh --disable-Cocoa --disable-Carbon --without-epath --disable-bonobo
--enable-debug --with-popt=/opt/local</verbatim>
- Other notes:
- The first time do a "make install" to ensure that resources are copied to the proper directories under =/usr/local/share/abiword-2.5=. Next time you can just do "make" to and launch your builds, practical if you'll be modifying the code.
- Launch AbiWord using =.../abiword/src/wp/main/unix/abiword"= or =/usr/local/bin/AbiWord-2.5=
- Compiled using OSX terminal, launched using X11's xterm.
- If you get an error saying that =configure= has errors try adding =ACLOCAL_FLAGS=-I -I /opt/local/share/aclocal= to your terminal =env=.
- Also make sure your =PATH= looks something like this both on your Terminal and X11 xterm: =PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/X11R6/bin=.
- I don't recommend using Fink, it gave me lots of problems and usually only installs binaries not the sources and libraries needed to build AbiWord.
--enable-debug --with-popt=/opt/local</verbatim>
- Other notes:
- The first time do a "make install" to ensure that resources are copied to the proper directories under =/usr/local/share/abiword-2.5=. Next time you can just do "make" to and launch your builds, practical if you'll be modifying the code.
- Launch AbiWord using =.../abiword/src/wp/main/unix/abiword"= or =/usr/local/bin/AbiWord-2.5=
- Compiled using OSX terminal, launched using X11's xterm.
- If you get an error saying that =configure= has errors try adding =ACLOCAL_FLAGS=-I -I/opt/local/share/aclocal= to your terminal =env=.
- Also make sure your =PATH= looks something like this both on your Term
inal and X11 xterm: =PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/ usr/X11R6/bin=.
- I don't recommend using Fink, it gave me lots of problems and usually
only installs binaries not the sources and libraries needed to build AbiWord.
'This last point, as all above may be inaccurate', I'm just trying to help ;)
-- Main.MartinSevior - 12 Apr 2007
-- Main.RiveraE - 03 Jun 2007
