DP Code - Proofreading Interface Rewrite

From DPWiki
Jump to navigation Jump to search

The purpose of this document is to gather design requirements to implement a new proofreading interface that will replace both the current standard interface and the enhanced interface.

Introduction

The current proofreading interfaces are very dated. Modern web tooling allows for a much richer and consistent interface to be developed with things like inline and real-time WordCheck results. Moreover, the current interfaces use HTML frames, which are not supported in HTML5.

Process

Careful thought will need to go into the process used to develop a new proofreading interface. Humans dislike change and past experience (like the Navbar redesign, CSS updates, changes to the sidebar, new display image interface) has shown that the DP community is very passionate about the current UI.

To be successful, a new process will need to be developed for engaging with the community on the new proofreading interface -- attempting to build this by consensus will be an exercise in frustration for the developer and the effort will fail. Attempting to appease everyone by adding numerous configurable preferences is not recommended. While nerd-knobs (as they are called in the tech industry) seem like an appealing solution to resolving conflicting requirements, they end up causing complex and hard-to-maintain code in addition to an unintuitive UI.

Whatever is developed will make someone unhappy and someone will complain. There is simply no way around this.

Technology

The new proofreading interface should be a largely stand-alone set of JS code that uses a DP RESTful API to interact with the code. The code should make AJAX calls to do things like save the page, query for words that WordCheck would flag, request the next page, etc.

Considerations

Some possibly-not-intuitive things to consider when designing the interface:

  • The proofreading interface, or at least components therein, should either be built on or replace the image viewing and text viewing components of the new display image interface.
  • The mentors interface should use the new proofreading interface to enable their use of the proofreading tools -- but not allow them to actually save the page in the round.
  • The quizzes should use the new proofreading interface -- in part or in full -- as well.
  • Different rounds will want different functionality but the interfaces should be largely congruent.

Current function decomposition

The current interfaces provide the following functionality

Metadata functions

  • load project comments
  • view image in new window (standard)
  • Show all text (in new window)

Page functions

  • Return to round
  • Report bad page
  • Save in-progress
  • Save as Done & Proofread Next Page
  • Save as Done
  • Stop proofreading
  • Revert to last save (enhanced)
  • Revert to original (enhanced)

Interface layout functions

  • swap horizontal / vertical
  • image / page frames are resizable (standard interface)

Image functions

  • zoom via user input (enhanced)
  • % zoom in (standard)
  • % zoom out (standard)
  • zoom 100% (standard as "original")
  • refresh image (enhanced -- what does this do?)

Text functions

  • change font (enhanced)
  • change font size (enhanced)
  • WordCheck
  • Format Preview

Text modifiers

  • character picker widget
  • Remove markup from selection
  • uppercase
  • title case
  • lowercase
  • [Greek: ]
  • [** ]
  • []
  • {}
  • [Blank Page]

Additional ones when formatting:

  • italics
  • bold
  • smallcaps
  • gesperrt
  • <f>
  • [Sidenote: ]
  • [Illustration: ]
  • [Footnote #: ]
  • /* */
  • /# #/
  • <tb>

Pop-up Tools

  • Search/Replace
  • Greek Transliterator
  • Hieroglyphs

Documentation

  • Guidelines
  • Help
  • (Workflow? I thought there was a link at the bottom of the page to a workflow chart. Has this been removed?)

Brainstorming

Task 1882 includes links to several tasks over the years regarding proofreading interface feature requests.

These are the things that I've heard people mention they would like to see changed in or added to the current interface. Because things are in this list doesn't mean they will change but is simply a discussion starting point. Please add your own to this list.

  • The edit box needs to automatically be the Right Size and not require manual intervention either via adjusting settings row/column sizes in Preferences or relying on the browser's capability to resize the textarea. For the Vertical layout I believe this translates to having the textarea fill the maximum width and height of its container. For the Horizontal layout, it should probably be the maximum height of the container, but perhaps not the width.
  • Ability to see both the image and the page text when running WordCheck.
  • Ability to change other page text besides flagged words when running WordCheck.
  • When running WordCheck, the image in the Enhanced Interface isn't centered like it is in the Standard Interface. This is most obvious when running in the horizontal interface with a very large monitor. (Note that this occurred for the old spellcheck code too and is not related to the new WordCheck.)
  • When running WordCheck, the image in the Enhanced Interface is reset to its original zoom and pan, it would be nice if it would retain its state throughout the page editing session. (Note that this occurred for the old spellcheck code too and is not related to the new WordCheck.)
  • I (itayperl) find myself many times looking at the previous page to the one I'm editing (e.g. for seeing the beginning of a split word). A convenient way to view the previous page image would be very useful.
  • Provide some way to align the scan and text in the horizontal layout. For example when there are two columns in the scan, when proofing the right column, be able to align the text with the right scan column. This can be partially done by narrowing the text by using the corner sizing tool, but this is centered between the columns. (This may be stated more technically in one of the descriptions below.) (WebRover added May 13)
  • A scalable, responsive interface that adjusts to all kinds of screens and resolutions, as well as being optimized for on-screen keyboards (both on desktop and mobile) without having to manually adjusting the proofreading interface resolution through DP settings (i.e. lower resolution screens, high-resolution monitors, mobile devices and tablets, foldable devices etc.)
  • Scalable icons that work well in accessibility settings (e.g. high contrast), follow a consistent color palette (e.g. Material Design, GNOME, KDE) as well as DP's own branding guidelines and have a consistent, polished look.
  • Interface settings should persist after they are made without a special "save" step.
  • Support for more special characters and symbols (maybe a Windows Character Map type menu for choosing and inserting all special characters?); and adding more characters (perhaps a poll or survey in the forums to see which ones should be added) to the existing tiled character picker (if that is going to be kept).
  • a way of spelling out the full Unicode name of a given character (e.g. by cutting and pasting that character in a special edit box), e.g. to help disambiguate A / Alpha when in doubt
  • A WordCheck page status icon that shows if you've run WordCheck on that page or not (similar to the current ones on the Project pages).
  • The Icons/functions listed above are not in the same order they appear on the enhanced interface. If they are in the same order in the standard interface then I'd like to see the list above reordered. (I'm happy to do this, if someone confirms it.) If they are in a different order in the two interfaces, a recommendation is to make them the same order after the rewrite. (WebRover May 13)
  • Buttons: Too much of a forest at present and not easy to locate your way forward or out. WordCheck only needed in Proofing rounds. Preview only needed in Formatting rounds. Is Show All Text needed at all? How about Bad Page (very rare)? Scrap Stop Proofreading. Have top row to save or abandon the page - Save Done, Save In Progress, Return to Round; second row to go places - WordCheck/Preview, Next Page, Exit (to project page); third row Switch View and anything else. (Noyster June 28, 2020)

These are the things that I've heard people say must be retained out of the existing proofing interfaces:

Distilled features

These are items that have been distilled into specific, implementable features from the Brainstorming list above. Please allow a developer to edit this list since they will know better how hard it would be to implement the feature in the current codebase. Discussion on if they distilled it right is always welcome and encouraged.

Image viewer features

(most of these have already been implemented in the new image viewer widget already in the PIs)

  • No triangle image moving icons - forumpost:305261
  • Make the image pannable via draggable ala Google Maps
  • Support pinch to zoom
  • Add image zoom controls directly to the image frame (ala Google Maps).
  • Zoom must be accessible from icons - forumpost:430476
  • Zoom must be accessible by percentage - forumpost:430477

Editing interface features

  • Must support both vertical and horizontal layouts - forumpost:1902
  • Scroll bars in the image viewer interface - forumpost:304646
  • Ability to adjust/resize the image frame vs the text frame (Standard Interface) - forumpost:656488
  • Zoom must be accessible from icons/buttons (Standard & Enhanced Interfaces) - forumpost:430476
  • Zoom must be accessible by explicit percentage (Enhanced Interface) - forumpost:430477, forumpost:656454
  • Use a single-page (ie: non-frame) layout using CSS layout tools. To make this optimal, it will require CSS manipulation via JS
  • Use AJAX to do piecemeal transactions to the server instead of re-requesting the entire page for WordCheck, for instance.
  • Provide access to both WordCheck output, the image, and the text easily
  • Allow access to other check-related tools: eg: Punctuation, RegExs

Potential JS libraries to build on

See also: https://nexttexteditor.com/

Potentials:

Maybe not:

Other useful resources

Retrieved from "https://www.pgdp.net/w/index.php?title=DP_Code_-_Proofreading_Interface_Rewrite&oldid=129083"