fweeb / wordpacer Goto Github PK

1.0 2.0 0.0 230 KB

A little web app to help control pacing in your stories and other writing.

License: GNU General Public License v3.0

JavaScript 98.61% HTML 1.14% CSS 0.25%

wordpacer's Introduction

Word Pacer

In short, Word Pacer is a little web app designed to help you adjust the pacing in your writing. Whether it's fiction, essay, or poetry, the idea is that you can control how fast your audience reads (I call it reader velocity) by adjusting the length of your words, sentences, and paragraphs. That last sentence, for example, is long. It would slow a reader down. Here are the basic rules:

Long words, paragraphs, and sentences reduce reader velocity.
Short words, paragraphs, and sentences increase reader velocity.
Very short paragraphs and sentences (for example, one word long or one sentence long) dramatically reduce reader velocity.

There's some nuance in there, but that's the gist of it. When you paste your text, the graphs above show breakdowns of each paragraph and the lengths of each word in them. The red line indicates your reader velocity. You can zoom in on part of the graph by drawing a box in it. Or you can use the small navigation graph in the upper right corner. Clicking on individual words in the graph should highlight that word in the rendered text on the right.

Word Pacer primarily supports Markdown syntax with a couple additional features. For instance, the --- is an em dash (---). However, plain text should also work just fine so long as you have two carriage returns between paragraphs. Eventually, I'll add support for just plain text... and perhaps if there's interest, I'll see about adding other text formats.

Word Pacer is still very much under development. It should analyze 2000 words of text in just over 3 seconds after you click the Analyze Text button. If you're reading this, chances are good that I contacted you directly about checking it out. Please use the Issue Tracker for giving me feedback (you can also hunt me down via email or social media, but the Issue Tracker is easier to follow). I'm mostly interested in feedback on the user interface, performance, and the accuracy of the reader velocity calculations... but I'll take whatever you've got.

Known Issues

I'm not overly fond of the name. :P
Site has only thusfar been tested in Firefox and Chromium. Test results from other browsers are most welcome.
Highlighting doesn't work for hyperlinks included in the text.
Abbreviations like e.g., i.e., Dr., etc. tend to mess up velocity calculations.
Lists (ordered or unordered) mess up highlighting and paragraph calculations.
Graph does not update as you type; you must click the Analyze Text button. This is mostly a performance issue. I'm open to suggestions to how to make the graph update in real time.
There is no lexical analysis of the text. Reader velocity is calculated entirely with word length, sentence length, and paragraph length.

Legal Notices

License

GPL v3

External Libraries

wordpacer's People

Contributors

Stargazers

Watchers

wordpacer's Issues

Real-time graph updates?

The current usage workflow requires that a person click the Analyze Text button to see any updates in the velocity graph. It would be much nicer if, like the Markdown parser, the graph automatically updates as the text is being written. Achieving this, however, might require some major work.

A bit of a performance boost can be had by changing how the text is collected/saved/parsed. There's currently no caching... so the text is ingested and processed in whole each time. Treating the text as a stream should yield better results on the data collection and calculation side of things.

The other slowdown, however, might be in jqPlot itself. I'm not sure I can make that any faster on my own... and I'm not sure that there are any other graphing/plotting libraries in Javascript that provide better performance. Suggestions welcome.

Always show stats

I think you have enough screen real estate, and they're interesting to see.

Stats rounded to an integer are enough. So Minimum reader velocity: 114 please, not Minimum reader velocity: 114.58333333333333

If there are reasonable benchmarks to show, that would be useful. I.e. average word length here is interesting, but it would be more relevant if I could compare it to a benchmark like "Mary Had a Little Lamb" or the script to "Killdozer 3: Now It's Personal"

"Show Labels" is cluttered in the zoomed out view

Consider only showing labels when zoomed in and autohiding otherwise.

Alternatively, it may be nice to have a mechanism to show a small floating window of text with the relevant sentence or paragraph fully visible while your hovering over relevant sections of the graph. This may require some more direct hacking on jqPlot to work properly, though.

Need to make exceptions for common abbreviations

Abbreviations tend to mess up velocity calculations by prematurely marking a sentence as ending. I can't cover all abbreviations, but it'd probably be a good idea to address common ones like the following:

e.g.
i.e.
Dr.
etc.
Mr.
Mrs.
Ms.
St.
vs.
v.

The difficulty is that I'm currently using a very simple regex to separate sentences. Building exceptions like this could complicate that regex pretty heavily.

Lists (ordered or unordered) mess up highlighting and paragraph calculations.

The velocity graph assumes paragraphs are in header or paragraph tags. Lists are currently not accounted for properly.

"Paste your text here" is misleading as a heading

Since it is rendered much larger in the Markdown output, it's size suggests that you should paste text where you can't actually do such a thing

Add support for plain text

Currently, Word Pacer only supports Markdown. However, it should be expected that people may paste in text from other documents. This text will not be in Markdown. The biggest complication here is that Markdown assumes a new paragraph after two carriage returns whereas most word processing software uses only one carriage return and then uses styles for spacing. That means that paragraphs would not be properly recognized in pasted text.

There are two possible solutions:

Automatically convert plain text to simple Markdown when it's pasted by adding those additional carriage returns.
Have a plain text mode that recognizes a single carriage return as being a new paragraph.

I'm not sure which is the best solution. The first seems more elegant, but I'm not sure if it's possible to pre-process pasted text... and I'm if it would be disorienting to a user to see the result being something slightly different than what they copied. The second is certainly easier to do, but it requires an additional toggle in the UI and I'd like to keep those to a minimum.

Loading bar or working spinner?

Processing large amounts of text is time-consuming. If performance can't be improved it would be wise to let the user know that something is actually happening. Since this is all pure client-side Javascript, that might be a little tough (there's no AJAX asynchronous stuff going on). Javascript on the page would just need to load smarter... and perhaps cache locally.

Highlighting doesn't work for hyperlinks included in the text.

If there are hyperlinks in the text (generated by Markdown), the highlighter doesn't account for the HTML mark-up around the highlighted portion of text. This needs to be fixed.

Analyze button is not prominent enough

Considering the fact that currently the graph doesn't update until you click the Analyze Text button it should be larger and/or in a more expected location.