Public:CWRC-Writer 0.17 Documentation
From CWRC
CWRC-Writer is an in-browser text markup editor being developed by the Canadian Writing Research Collaboratory (CWRC) for use by collaborative scholarly editing projects. This xml editing tool is still very much in development, but as CWRC-Writer develops, we expect to be able to release an open source in-browser scholarly editing tool with the following features:
- Close-to-WYSIWYG editing and enrichment of scholarly texts with meaningful visual representations
- Ability to add Named Entity Annotations
- Ability to combine TEI markup for the text and stand-off RDF annotations
- Ability to export using “weavers” that recombine the plain text, the TEI, and the RDF into different forms (including a TEI-like embedded XML)
- Documented code for editorial projects to be able to incorporate CWRC-Writer into their projects
CWRC-Writer Version 0.17
Version 0.17 is still very bare bones, but you will see that we have already made some changes based on testers' feedback on our first testing version, 0.14. Here is what you can see in Version 0.17:
- Like version 0.14, version 0.17 has a minimal interface that looks like other in-browser editors that you might have seen for editing html documents in content management systems (e.g. when editing pages in Blackboard, or even in html email editors such as Google mail). The difference with CWRC-Writer is that you are editing XML and can tag different entities such as places, names, dates, organizations, and events.
- a set of minimal TEI-oriented tags for structuring the document: there are five XML tags that you can use to structure your document: p [paragraph], emph [emphasis], title [publication title], quote [quotation], head [section heading]. These will produce formatting effects in your file, but of course the formatting is not dictated by the structure: the tags could have different formatting with them down the line (e.g. single quotation marks rather than double ones for quotations).
- a set of tags for marking up entities such as places, names, dates, organizations, and events. These tags were available by clicking on a drop-down menu icon in version 0.14, but in 0.17 they are available as separate buttons along the top of the editor.
- the text box will be blank, and you will have to paste your own text into the text box (for this you could use a document of around one page from your project to which you would like to eventually add markup).
- you will not be able to load files in this version (this functionality will come later). In the meantime, however, we have set up authentication, and when clicking on the "Save" or "Save As" buttons you can save your file as a test file to work with while testing this iteration, and you can use the "Load" button to bring up that file. However, because at the moment we do not have authentication set up for each individual user, it's probably best if you do not play with each other's files, so that each tester can have his/her own files to alter/add to and so forth.
- The username for CWRC-Writer is cwrc
- The password is cwrcy
Testing Instructions for Version 0.17
CWRC-Writer is available at http://cwrctc.artsrn.ualberta.ca/
- When you click on the link above, you will see "CWRCWriter v0.17" with a text box that says "Paste your text here." Find about 1 page of text (e.g. from your project or even just any text) and paste it into this box. You could also try pasting a longer text into this version, and tell us if that affects anything (i.e. does it slow things down?).
- Look at the layout of CWRC-Writer. Some things have changed since the last iteration.
- We've taken the entity buttons out of the drop-down menu and moved them along the menu at the top of the editor. We've also added a little colour bar underneath them, which corresponds with the colour used for each of these entities in the "Entities" tab on the left-side of the screen. What do you think of this? Are the icons for "Person", "Place", "Date", "Event", "Organization", "Citation", "Note", and "Text/Title" fairly intuitive? If not, what might you suggest that we change? (e.g. could one of the icons be different?)
- We've also added an "edit tag" button and a "remove tag" button along the top menu. Are these easy to use? Does it seem fairly simple and clear? Try investigating some of the different tabs and buttons. Without any knowledge of what these buttons do, and even if you have limited knowledge of how markup works, are they simple to figure out?
- Some dialogue boxes have changed, such as the dialogue box that pops up when you tag a date or tag a text/title. Try tagging a date and then try tagging a text/title. Is it fairly clear what you are doing when tagging a text/title?
- Try adding some entity tags to your sample text. You can do this by highlighting text and selecting the icon that looks like a scroll with a little green plus button on it. The entities, such as "person", "place", "date", "event", and so forth, are just random placeholders at the moment. However, we've added some entities from an authority list for the "person" entity, but these names only go up to H so far, so, for example, you will not be able to tag "Woolf" here. After tagging these entities, they will be listed in the entities tab on the left-hand side of the screen.
- Try to remove an entity. Is it simple to figure out how you would do this, based on how you added an entity? We now have a couple of ways to remove an entity: you can right-click and select "Remove Tag" from the right-click drop-down menu, and you can select the tag in either the left-hand tab or in the text in the editor and then click on the "Remove Tag" button on the top menu. We're also adding the functionality to be able to click on a tag in the entities or structure tabs on the left-hand side of the page and then hit the "delete" key, but doing so at the moment will end up closing the editor.
- Try adding some structure tags to your sample text. You can do this by highlighting some text, clicking on the tags drop-down, and then selecting a tag such as "paragraph", "heading", "emphasized", and so on. You will not see the formatting effects of the structure tags in your sample text, but you can see these tags by clicking on the structure tab on the left-hand side of the page.
- Did you find a bug or error, or you're not sure about how something works? Please feel free to email me with your questions! You could also email me (s.hesemeier@ualberta.ca) using the basic bug-reporting info below:
What browser were you using? On what OS?
What version of the editor?
When did it occur? (date/time)
You could add a screenshot as illustration if this is easy for you to do; otherwise, don't worry about screenshots.
Steps that led to the error.
Text of document that was tested.
Short description of error.
The first testing version (0.14) was mostly to test its look and layout; you cannot yet do everything in it that you will be able to do in other versions of CWRC-Writer (e.g. saving files). If there's something that you hope you'll see in later iterations, though, please let me know! (s.hesemeier@ualberta.ca)
Changes to Version 0.14 for Next Iterations
(from email July 25th, 2011)
The first eight are for version 0.17, with the rest up for discussion or for future versions.
1. Buttons for entity tags
2. Titles as entities rather than structure tags (if selecting "title" in the structural tags, would also then select title as an entity, with a list of titles to select from?)
3. Add a way to remove structure tags (use outline view)-- at the moment can do ctrl click to delete, but this is not apparent to most users-- should click on tag & delete key to remove it
4. Option clicking on text to change formatting or delete it (and on entity tags)
5. Brackets should not remain after an entity is removed
6. Instead of clicking "ok", it would be better to just hit the return key after adding tags
7. In view source, add an option button to edit the raw xml directly
8. Make dates not have to include day, month, year (should be able to choose only the year, or only the month, or only the day, and be able to include a date range-- e.g. July 22-25)
9. Overlap: force people to make a choice as they are tagging (I think I missed a detail here, so please clarify)
10. Styling of the text should be what people are used to reading/writing in-- i.e. WYSIWYG-- the text shown in the editor will have to be in the internal format-- i.e. any CSS styles should be applied to the internal editor document view.
11. Saving files to the server, and some sort of authentication so that people can log in and see their text & entities for their project
12. Entity lookup, export, and saving
13. Exporting tools
14. Intelligent stripping of tags if people paste in formatted text? i.e. paste as is or paste without structure, or paste from MS Word (import & paste function should be different-- import xml would bring up a request for a schema)
15. Automated generation of structural tags?
16. Allow people to search for elements? (and take out "entity" and other terms)
17. Language skins: for 0.16 or 0.17, have a French editing option
18. Command Z for undo (I can't remember if we said we'd add this, or for which iteration)
(from email July 27th, 2011)-- expanded instructions
1. For the buttons for entity tags, could you use the icons that are already being used for the entities in the drop-down list, and make them a bit larger?
i. e.g. for "person" there is an icon of a person, earth icon for "place", calendar icon for "date", and a birthday cake icon for "event".
ii. For "organization", we could use a non-gendered group of people icon (attached-- I got that one from filevector.com and it's supposed to be free, but I'm not sure how it would look as a small icon), rather than the current one (it was hard to tell that the current "organization" icon is an office building of some sort).
iii. The name "Bib. Ref." should be changed to "Citation", and its icon should be a card catalogue (2 sample icons attached).
iv. Instead of a pencil for the "note" icon, it should be a notebook or the scroll icon.
v. The mouse-over text (alt text bubble?) for all entities should say "Tag Person", "Tag Place", and so forth, rather than "Add Person", "Add Place". For removing entities, the button should be an "X" button (attached).
2. Text/title entity: The idea here is to create a single instance of markup that could be exported both as a TEI title tag AND as an annotation that labels an entity in a bibliographical repository. Depending on user export options and what information is provided, it could function as both a title tag and an annotation, or just as a title tag. This is not dissimilar to what we're doing with names/person entities, which will be exported as name tags and/or rdf entities.
i. Use a book icon for title, replacing the Citation (formerly the Bib Ref) entity with an index card icon.
ii. Mouseover text would say "Tag Text or Title"
iii. Popup dialog: relabel “Level” to “Type” [NB: this is just a change of label, 'level' is the actual name of the attribute]
iv. Type dropdown menu in popup would include:
radio buttons for the following values (bracketed text may be a help link if the box is getting too cluttered)
Analytic (article, poem, or other item published as part of a larger item);
Monographic (book, collection, single volume, or other item published as a distinct item) [this should be the default value that is adopted if someone simply hits enter after selecting the text/title button]
Journal (magazine, newspaper or other periodical publication)
Series (book, radio, or other series)
Unpublished (thesis, manuscript, letters or other unpublished material)
a separate check box for:
Unformatted (e.g. to tag text without stating title, e.g. "her first novel" for The Edible Woman)
retain the option for what was input as "Reference" but use the label as specified in the wiki documentation for the structural tags, i.e.:
Equivalent title (optional): [text input box] (standard form of title, e.g. Roughing It in the Bush if readable text uses the short version Roughing It)
add an option for:
Refer to text (optional): retain this and allow free text input [this is what would hook into the text entity lookup
system: it would be great if we could hook it up the CWRC repository bibliography search in a while]
Note that the TEI values, formatting, and help text are documented in the wiki: http://cwrc.cs.ualberta.ca/index.php/CWRC:Editor_TEI_elements#
For a full example of what will be produced by the button (as xml or rdf or some pseudo representation), I can get Mariana to help me do up something as an example, if you still need that.
3. Instead of the "Tags" drop-down menu, this should say "Structural Tags". There should be three options to remove structure (as well as entity) tags: 1) right-click & select delete; 2) click the tag in the structure pane and then press the delete key; 3) click on the tag in the structure pane and select the X button (icon attached). The x button would not just be used to remove entity tags, but to remove structure tags as well.
4. Similar to the option in #3 to remove tags by right-clicking, people should be able to right click on any tagged text to delete formatting.
6. At any point, people should be able to hit return rather than clicking "ok" (i.e. not just when they are in a certain field)
7. If it will take a lot of time to allow people to view source and edit the xml directly, don't worry about that for this iteration. We discussed the possibility of allowing some people to try this, I think, but all of our current testers are fairly comfortable with xml and they should be okay with being able to access and edit the xml.
8. Diagram attached to show what the date popup would look like. People should be able to tag an entity as either a date or a date range using radio buttons.
All tags should also have default values wherever possible (lang = Engl; title = monographic).
(from email August 30th, 2011)-- bugs and changes
Hi James, Geoffrey, and Susan,
The following is what I have noted from our Skype call today.
Before the next iteration, James will fix the "ok" button issue (mentioned below) and any quick fixes by Friday, Sept. 2nd. I've attached a few screenshots, but if you'd like more, please let me know.
Bugs/fixes:
- add an "ok" button that people can click on after selecting to tag text/title, tag paragraph, tag quotation, and so forth, in addition to being able to hit return. Right now there is only a "cancel" button, and even though you can hit return to add the tag, it might be confusing for people not to have the "ok" button as well. Also, when I select any option other than monographic when tagging text/title, I cannot add the tag, even after I hit return (and I also had problems adding other tags by just hitting return, such as quotations, and people also may not realise that they have to hit return) [see "ok_button" screenshot]
- if you select the last word at the end of a line of text that has no punctuation at the end of it, double click that word, and then click the icon at the top of the page to tag it as a citation or note, you get an error message that indicates that you are trying to add invalid markup (saying that the beginning and end have to have a common parent, and so forth). [see "common_parent_error" screenshot]
- pasting a text from html keeps the html formatting, not just within the view source, but also within the text displayed on the screen (i.e. it will include bullet points). [this was deemed not to be something that needed to be changed immediately, but as something that might come back and get us down the road when applying a schema to pasted text]
Changes:
(for this iteration, do whatever is quick: this list begins with the changes that could be for this iteration and then ends with ones that we discussed for future iterations, with some flexibility on what would be done for this iteration and the next):
- the structural tags drop-down along the top menu should say "tag structure" beside the < > icon. There should also be a little arrow to indicate that it is a drop-down list. [see attached PDF "CWRC-Writer0.14_changes_sketch2"]
- users should be able to right click on tagged text and, in addition to being able to add or remove tags, they should be able to also click on "edit tag" (e.g. to change the language of a quotation tag). Users should be able to do this either by right clicking or by selecting entities through the entity tab on the left side of the screen.
- in the structure tab, users should be able to right click to remove paragraph tags (as with the "emphasized", "quotation", or "heading" tags), but doing so would only remove the paragraph formatting and not remove the text of the paragraph (we were going to let users be able to select a tag in the structure tab and then the "delete" key to remove that tag, but then this was deemed to be too confusing since it might make users think they are deleting the text of that tag)
- eventually we'll also figure out how to deal with adding citations-- at this point, tagging for citation doesn't require any format and just adds a note. In the meantime, however, if tagging as a citation, the entity in the left-hand entity tab should say "citation" rather than "note", because this might be confusing to users (since "note" is another entity). [see attached screenshot called "citation"]
- would it be possible to add icons to entities listed in the entity tab on the left side, or add under each entity icon the colour that is used for each type of tag (e.g. orange for dates), so that there is a clearer connection between the colours and icons for the different entities? This could be done perhaps by just adding a two pixel colour bar underneath each of the entity icons along the top of the screen.
- users have the option to select the "unformatted" box when tagging text/title: this option should also be available for other tags such as "quotation". In other words, should we give the option to turn autoformatting off, and could people apply their own formatting? e.g. what if I cut and paste in text that already has quotation marks around quotations?
- create a "new" button (with "new document" alt text) that would create a blank or fresh document. The editor should first prompt the user to ask whether s/he wants to save the existing document.
- the "load", "save", and "save as" buttons should be moved to the left along the top row, before the structural tags drop-down and the entity icons. Perhaps it would also be possible to extend the top tab to put the "new", "load", "save", and "save as" buttons above the entities tab and structure tab in the top left-hand side of the screen.
- there should be an overall setting to set defaults, either specific to each project once we have the ability to have each user authenticate, or by having the editor only ask once for paragraph language, and if the user selects "English", then it will not keep asking this every time the user tags a paragraph. If the user wants to change the language from the default, s/he can click on "edit tag" to do so. This could be kept track of in each session.
- eventually to be able to type "q" and get to the "quotation" tag in the structural tags drop-down, and to do the same for other lists. This will be important when we get to real schema and bigger projects that might have long lists.
- eventually we'll have upload/download like Google Docs or an export feature; at the moment, people can save files to a directory on the web server Kamal set up for the project. SH will tell people not to play with each other's files for the time being (or perhaps to personalize them somehow-- i.e. with their initials in the file name). Eventually we'll have separate user logins/accounts in which files would be saved.
- we'll also eventually have to think of how to "chunk" texts-- i.e. how to work with bits of documents. Also, is the editor's speed with larger texts something we'll have to consider? Can people work with novels in the editor?
Brainstorming about next steps:
- next iteration should produce something usable by CWRC participants - validation and handling of much more complex structural markup - entity management, help text, eventually French - getting entity indexes, export, and so forth would require backend work - RDF: it shouldn't be a huge amount of work to convert to OAC/RDF. What do we intend to do with RDF? - next contract to have server-side API stuff? (to see the files they have online?). Can't do server-side stuff yet? Do a server-side project that can dovetail with this?
GR and SB to work with JC on parameters of new contract. After end of Skype call, GR and SB to discuss what the next milestones would be.
Other meeting notes:
SH to look up TEI rules on whether heading tag has to be in a paragraph or if it can be in a block on its own.
SH will make sure emails outlining changes from past versions are up on the wiki (e.g. the email about changes for v 0.17)
SH to send out heads up email to editor testers on Aug. 30th [didn't have time today so will do tonight or tomorrow] and will send next iteration email on Sept. 6th - will let people know that the names in "Tag Person" are only A-H (e.g. won't get Woolf). SH will explain that the names are from CanWWR, CEWW, & Orlando and are still just for demonstration purposes. Individual projects may have their own authority lists for names and so forth. - will tell everyone that we really appreciate their feedback but that we haven't had a chance to implement everything
SH to add to editor documentation on wiki before next iteration; wiki documentation should be kept up to date (i.e. 0.14 version archived and then expanded/changed to keep up to date).
People at the CWRC workshops may want to be added to the testing group; for the time being, good to stick with our current group.
All best,
SH
