Wow, what an awesome reply! Really appreciated, thanks a ton! On Fri, Apr 29, 2011 at 9:13 AM, Daniel Danilatos <[email protected]> wrote: > Awesome. Sounds like the editor already does a whole bunch of what you > need. I was wondering if you'd want to even decouple the editor from > XML, which is a goal, and not too far off, but seems like you don't > need that so that's even less work. > > I really hate using email for this kind of thing... :) but here goes:
I'll add a few inline responses, and then let's move to a wave (wave.google.com? waveinabox.net? I'm "t.broyer@..." in both places) > Στις 29 Απριλίου 2011 2:00 π.μ., ο χρήστης Thomas Broyer > <[email protected]> έγραψε: >> - the documents have to be stored in (or easily converted to) XML >> with strict schemas (looks a bit like DocBook); we actually don't have >> any constraint re. the storage format > > So, annotations out of the question? They really do solve many > problems in a nicer way than XML, even without the need for concurrent > editing. XML is great for structure; annotations are great for... > annotating. > > It is also entirely possible to use annotations internally, and then > export to XML. That's what I had in mind: store "as close as 'internal representation' as possible" and turn into something else only when needed (basically, exporting to the DocBook-like XML schema) Or maybe do the transformation before storage, but the key point is: send annotations to and get annotations from the editor (additionally, this would mean using the built-in handlers for those... annotations, rather than having to code new ones working with elements instead) >> - images (with caption; à la HTML5's <figure>); these are linked to >> "illustration" domain objects (including the caption). In the text, >> the user can define the size of the thumbnail, how text flows around >> the figure (float), and change the caption's text (could be done in, >> say, a popup, not necessarily by directly editing the text displayed >> in the editor) > > Image thumbnails pretty much do this already, except for the arbitrary > size, but that should be simple to add. The rest is pretty much > already implemented. Well, in our case, the caption shouldn't be stored in the doc, but rather "pushed" to the domain object when modified by the user (i.e. maybe it'll be read-only in the editor, if possible, and modified only through, say, a "change caption" dialog box). But of course the thumbnail doodad will provide a very good code base! >> - "semantic" markup is >> - mostly about attaching a domain-specific term/category to the >> selected text, e.g. this is a person, date, building material, etc. >> (there are something like 50 thesaurus/list-of-values to choose from; >> the user "attaches" the selected text to one such thesaurus, and can >> optionally select a specific value from the list) I don't know if >> annotations would be the best fit here: we don't have the constraint >> of running through several paragraphs, but it's likely that, despite >> not spec'd, such semantic markup shouldn't overlap; so elements could >> be used; plus, the value being optional could make it impractical to >> distinguish "start of annotation without value" from "end of >> annotation" (if we use the DocInitialization XML representation). > > annotation values are opaque strings, so you can choose to interpret > them however you like. if a particular annotation has no value, but is > merely a marker, then an empty string, or single letter, would suffice > as marking it "present" (null being absent). OK, so you'd still go with annotations for that use case. My last note about the possible issue with optional value was related this comment in DocOpUtils: // This code renders ending annotations and annotations that are // changed to null the same way, which is OK since we are // only concerned with DocIntializations. (It's, in fact, the // only correct solution since our test cases use this code for // equality comparison of documents.) But re-thinking about it (and looking at the client-server protocol), annotations are probably best serialized separately, along the lines of the Wave API's Blip object, rather than in the form of "annotation boundaries" (like in ProtocolDocumentOperation and DocOp/DocInitialization); or if in the form of annotation boundaries, make sure to serialize 'null' differently than the empty string. >> - there are also 10 cases where the annotation isn't linked to any >> thesaurus (e.g. marking up a birth date, a person's given name, a >> book's publish date, etc.), in this case, we could have a single >> "kind" with 10 possible values (i.e. kind="birthdate"). > > not sure i understand - do you want an annotation with multiple values > at once, or more like an enum i.e. can take on one of several possible > values? (both doable, several strategies depending on use case > specifics). Simply an enum (I was just trying to be exhaustive in listing the features). >> This editor will be used in a dozen places (fyi, we have something >> like 100 different "forms"), with different features: >> - "graphical" markup is always "on" (I thought there was one case >> where it didn't, but re-reading our specs, it seems I was wrong) >> - "structural" markup can be disabled (i.e. a single line/paragraph; >> looks like the LinoTextEventHandler could help here), partially >> enabled (paragraphs, headings and figures only; no text-align, list, >> table or link; there's also one case where there are only paragraphs >> and headings) or fully enabled (in a couple places only) >> - "semantic" markup is always on, but the set of thesaurus/LoVs to >> choose from is different each time. > > perfect - you just register the right set of doodads for the features > you want enabled. think of the editor not as an editor, but as "editor > tools". you build your editor by composing together the bits you want. > put all the bits in for the fully featured version, put only some bits > for the simpler version, etc. Would you use different schemas too? (e.g. to handle the case of someone pasting a table or figure in an editor where it's not allowed) >> There are two cases where the edited document can (theoretically) be >> very large ("up to 80 pages"), and obviously these are the cases where >> all the features are enabled: think domain-specific Google Docs! > > currently the editor has no pagination, i.e. it holds the whole > document in memory. so there would be upper limits (though i've tested > it on quite huge documents and it worked fine). If it fails or becomes sluggish with very big documents, well, I think they'll just write smaller ones ;-) We'll see when it happens (if it ever happens!) >> I thought about Wave's editor because it is "schema-based" and because >> of the "structural markup" constraints, particularly when pasting >> things coming from, e.g. MSWord (something that's likely to be common >> in our case). We specifically don't need OT or collaborative editing, >> "just" a rich-text editor with the special features described above. > > no problem. the copy/paste code atm is the most hard coded part of the > editor. we'd need to make it more pluggable so you can customize how > it converts pasted rich text html into whatever data model you have. OK, I'll tackle that later on (among the mentioned use cases were writing in MSWord –or similar– and then copy/pasting the whole doc into the editor, and preparing some tabular data in MSExcel –or similar– and then copy/paste it as a mean to easily add a table to the document) > the good news is, it already supports "semantic" copy/paste, which > means that if you copy between two wave editors, it won't get degraded > by going through an intermediate clipboard html format - we preserve > the original annotations, elements, attributes, the lot. Yes, I saw that. This is great! >> To limit the amount of work, I though about using the Wave's way of >> marking up <line/>s, at least at the beginning; but maybe it'd be easy >> to use a more HTML-like <p>...</p> and <h1>...</h1> kind of markup? >> (and keeping <?a ?> annotations for styling) At first sight, it looks >> like the Editor is quite tightly bound to <line/>s, but maybe it's >> just me? > > There may be a couple of hard coded bits here and there but it's > definitely not tightly bound, OK, that's good news. I think I'll stick with <line/>s until I put everything else in place, and then iff <p>s looks more appropriate to our use then maybe I'll try to replace <line/> (and remove the hard-coded bits; btw, I just stumbled on a few ones in ContentDocument#checkHealthy and debugCheckHealthy) > in fact, it used to be that we had > <p>...</p> and <h1>...</h1>, but we moved away from it for OT reasons. > There is still some unused code in there for working with paragraphs > (though most has been deleted). org.waveprotocol.wave.client.editor.content.paragraph.Paragraph is still there, and register()ed in Editors#initRootRegistries (and used by the form.input doodad). >> If you could give me hints about how best to: >> - initialize an Editor (use an "owned" ContentDocument or not? what >> should I register in the registries?) >> - put content into, and get content out of the editor: should I >> rather use the "persistent document" (and if yes, which class: >> PersistentContentDoc, ContentRawDocument? I must confess I'm lost with >> all these classes and interfaces) or a "doc initialization"? >> - make my own schema(s), and how to map the "structural" and >> "semantic" markup (elements? annotations?) >> It'd help me start customizing the editor to my needs and see what >> could be improved to make it a standalone component (starting with >> writing some docs! ;-) ) > > i don't know if these have already been migrated to confluence, but > here's something better than nothing: > > http://www.waveprotocol.org/code/tutorials/writing-a-doodad > http://www.waveprotocol.org/protocol/design-proposals/editor > http://danilatos.com/Wave_Summit_2010_Editor.pdf (this might be > published somewhere else properly, but i couldn't find it, so i just > put it here for now). Awesome, thanks! I came across the first two (didn't read the first one as I was first interested in making a simple editor work and understand how to initialize it and how it works; and forgot about the second one, which was a bit hard to understand for me at the time) but your slides really shade some light on the overall design! (a picture is worth a thousand words) > The above should give you some idea, but a few pointers: Thanks a whole lot, I'll digest all of that and start coding a more featured prototype (I got a simple editor working, with a simple toolbar for turning bold on and off on the selection; based on the wavepanel.impl.toolbar.EditToolbar code; this one really deserves a bit of work to make it less "wave-centric" and a bit pluggable) -- Thomas Broyer /tɔ.ma.bʁwa.je/
