Public:CWRC-Writer Documentation

From CWRC

Contents

About

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. 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
  • And more!

Getting Started

1) Open CWRC-Writer in a Web browser, such as Firefox or Chrome (Internet Explorer is not supported). The latest version (0.18) is available at http://apps.testing.cwrc.ca/editor/devbuild/

2) You will be prompted to enter the username (cwrc) and password (cwrcy).

3) Paste text into the editor, or load a file that you have already saved by clicking on the "Load" button along the top of the editor.

Testing Instructions for v0.18

We have some basic documentation about the editor at http://cwrc.cs.ualberta.ca/index.php/Public:CWRC-Writer_Documentation, which includes the testing instructions for this version (0.18) and the two previous testing versions (0.17 and 0.14). For this iteration, in addition to commenting on features of the editor, we would like you to also comment on what you would like to see in the documentation about CWRC-Writer. Do you need "Getting Started" and "About" sections? Are there particular features that need more explanation? etc. Based on your feedback, we will be fleshing this out in the general CWRC-Writer Documentation page.

1) Log in to Version 0.18 of CWRC-Writer at http://apps.testing.cwrc.ca/editor/devbuild/

The username is cwrc and the password is cwrcy.

2) You cannot load files from your own computer for this iteration, but you can begin by pasting your text in the text box (e.g. a file from your project, or even just any text) or loading a saved file. To load a saved file, click on the "Load" icon beside the "Save As" icon at the top of the page.

3) As with the last version (0.17), when clicking on the "Save" or "Save As" buttons you can save your file on our server as a temporary test file to work with in 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 best if you do not play with each other's files: this way each tester can have his/her own files to alter, add to, and so forth. Perhaps personalizing your files by adding initals to the beginning (e.g. SAH) would be a good way to indicate to others that it is a file created by one of the other CWRC-Writer testers.

4) As with version 0.17, the entities, such as for "Place", "Event", and "Organization", are still just random placeholders at the moment. We added some entries from a sample authority list for the "Person" entity, although these names only go up to H so far, so if you try to tag "Woolf", for example, you will not be able to find Virginia Woolf in this list.

In version 0.18, however, we've added a "Create New" button that you can click on after selecting text to mark up as an entity, such as "Place", as this will be connected to the entity management system in future iterations and will allow you to add new entities. At the moment, however, it is just for demo purposes, and saves of new entities are not permanent.

5) We now have help text displayed for some tags, such as Div 1. Right click on a section of text, then select "Structural Tags" and then "Div 1", click on the "Help" button, and you will see the help text for Div 1. Some tags still don't have help text, but we're hoping that this can serve as a demo of what it would look like.

6) Validation of the whole text is coming. At the moment, the editor is using the Orlando events schema, and so it is limited, and the editor will only give you the tags that are valid at the point that you are inserting them.

7) Some changes in the layout/interface: - we now have the path of the tag displayed below the icons on the top of the CWRC-Writer page - you can cut and paste text, but moving large sections will cause the text to lose its tags and/or entities - the source view has changed a bit, but as with previous versions, it's best not to play around too much in "edit source" at this point

8) Have a look at this version of CWRC-Writer, play around a bit, and let me know what you think.

9) Did you find a bug or error? If you find any bugs or issues, please let me know (s.hesemeier@ualberta.ca) using the basic bug-reporting info below:

What browser were you using? On what operating system? What version of the editor? When did it occur? (date/time) Short description of error. Steps that led to the error. Text of document that was tested. You could add a screenshot as illustration if this is easy for you to do; otherwise, don't worry about screenshots.

Also, if you are unsure about how something works, please feel free to email me with your questions! As mentioned above, knowing what you have questions about will also help us with fleshing out the documentation for future iterations.

Overview of 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 an overview of 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 on our server as a temporary 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 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. Perhaps personalizing your files by adding initals to the beginning (e.g. SAH) would be a good way to indicate to others that it is a file created by one of the other CWRC-Writer testers.
    • 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/

  1. 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?).
  2. 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" (formerly "BibRef"), "Note", and "Text/Title" fairly intuitive? If not, what might you suggest that we change?
    • We've also added an "Edit Tag" button and a "Remove Tag" button along the top menu. Are these easy to use?
    • 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. We've changed titles to entities in this version rather than structural tags. Is it fairly clear what you are doing when tagging a text/title?
  3. Try adding some entity tags to your sample text. You can do this by highlighting text and selecting the icon for the type of entity that you'd like to tag (e.g. "Date"). The entities, such as for "Place", "Event", and "Organization", are just random placeholders at the moment. However, we've added some entries from a sample authority list for the "Person" entity, but these names only go up to H so far, so if you try to tag "Woolf", for example, you will not be able to find Virginia Woolf in this list. After tagging these entities, they will be listed in the entities tab on the left-hand side of the screen.
  4. 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 both entity and structure tags:
    • You can right-click and select "Remove Tag" from the right-click drop-down menu
    • 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.
  5. 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 can also do this by highlighting text, right clicking, and then selecting the tag from the "Structural Tags" menu. You will see the formatting effects of the structure tags in your sample text, and you can see these tags by clicking on the structure tab on the left-hand side of the page.
  6. Try editing a tag. You can do this by clicking on the "Edit Tag" button in the top menu, or by right clicking on tagged text or the tags in the Entities or Structure tabs on the left-hand side of the screen and then clicking on "Edit Tag". We've added the ability to edit tags so that you don't have to remove a tag and add a new one every time you need to change/update a tag.
  7. We've also added an option button to edit the raw xml directly. This is beside the "View Source" button on the top menu. At this point it would be best not to play around with that too much, however.
  8. And, we've also added Command Z for undo!
  9. Did you find a bug or error? We might try someting a little different for bug tracking in the next iterations. In the meantime, if find any bugs or issues, please let me know (s.hesemeier@ualberta.ca) using the basic bug-reporting info below:
  10. 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.

  11. Not sure about how something works? Please also feel free to email me with your questions!

The first testing version (0.14) was mostly to test its look and layout, and we've added more functionalities to version 0.17, but you still cannot yet do everything in it that you will be able to do in other versions of CWRC-Writer. If there's something that you hope you'll see in later iterations, though, please let me know! I'm also adding to the documentation available for version 0.17 at http://cwrc.cs.ualberta.ca/index.php/CWRC:XML_Editing_Tool

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.15

Version 0.15 is still very bare bones, but when it is released in mid-August, you will see that we have already made some changes based on your feedback on our first testing version, 0.14. Here is what you can see in Version 0.15:

  • Like version 0.14, version 0.15 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.15 they will be 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). For version 0.15, we will need you to send us a sample text of about one page for use in the editor.
  • you will not be able to save files in this version (this functionality will come later). In the meantime, however, we have set up authentication when clicking on the "Save" or "Load" buttons so that this functionality will eventually be available.
    • The username for CWRC-Writer is cwrc
    • The password is cwrcy

Testing Instructions from Version 0.14

CWRC-Writer is available at http://cwrctc.artsrn.ualberta.ca/

  1. When you click on the link above, you will see "CWRCWriter v0.14" 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.
  2. Look at the basic layout of CWRC-Writer. 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?
  3. 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. After tagging these entities, they will be listed in the entities tab on the left-hand side of the screen.
  4. Try to remove an entity. Is it simple to figure out how you would do this, based on how you added an entity?
  5. 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.
  6. 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)