summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAdrian Cochrane <adrian@openwork.nz>2020-06-06 12:57:46 +1200
committerAdrian Cochrane <adrian@openwork.nz>2020-06-06 12:57:46 +1200
commit7a7acaac7186a45d84ed09fbdc9356ec6683a79b (patch)
tree5b938e5833cf49d8da467d12c32043a9c7947a56
parente554659a39367c64ce2aa69ee8cc59c32effdbd0 (diff)
parentbf572743cd38f3b4ea5881e7a6473c087bc60356 (diff)
downloadrhapsode-7a7acaac7186a45d84ed09fbdc9356ec6683a79b.tar.gz
rhapsode-7a7acaac7186a45d84ed09fbdc9356ec6683a79b.tar.bz2
rhapsode-7a7acaac7186a45d84ed09fbdc9356ec6683a79b.zip
Merge remote-tracking branch 'contrib-ariana/doc-update'
-rw-r--r--CONTRIBUTING.md6
-rw-r--r--README.md2
-rw-r--r--docs/CSS-Speech-Tutorial.md100
3 files changed, 100 insertions, 8 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5824437..cfc1509 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,11 +1,11 @@
# Contributing
-You can contributed code or register "issues" to Haskell Stylist by contacting
+You can submit contributed code or register "issues" to Haskell Stylist by contacting
me (Adrian Cochrane) via [mastodon](https://floss.social) or [email](mailto:opensource@openwork.nz).
Or you can sign up for an account on the NZ OSS GitLab.
Any issues you report will be described in a markdown file within the ISSUES folder.
-To contribute code, you may either sending me:
+To contribute code, you may either send me:
* A link to your online fork from which you want me to `git pull`.
* git patch files, as documented at https://git-send-email.io/
@@ -14,6 +14,6 @@ To contribute code, you may either sending me:
* Create a UI for filling in webforms.
* Implement HTTP(S) caching.
* Add support for new network protocols.
-* Anything listed under the `ISSUES` folder, especially it's `help-wanted` subdirectories.
+* Anything listed under the `ISSUES` folder, especially if it's `help-wanted` subdirectories.
Feel free to ask me if you have any questions.
diff --git a/README.md b/README.md
index a8b21eb..a7c5684 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ Web browser targetting voice I/O.
See CONTRIBUTING.md for instructions on how to help the project.
## Desired Experience
-Rhapsode will read a webpage outloud to you according to some special CSS properties.
+Rhapsode will read a webpage out loud to you according to some special CSS properties.
Arrow key navigation will be supported for navigation between headings, paragraphs,
and table cells.
diff --git a/docs/CSS-Speech-Tutorial.md b/docs/CSS-Speech-Tutorial.md
index 1488b2c..fb13749 100644
--- a/docs/CSS-Speech-Tutorial.md
+++ b/docs/CSS-Speech-Tutorial.md
@@ -1,5 +1,7 @@
**Wanted:** Guidance on creating a great audio theme. Maybe based on voice acting
or public speaking theory.
+**Wanted:** Written descriptions of the various outcomes of properties. I.e,
+how does `speak-as: spell-out` differ from normal.
Rhapsode still lets you apply CSS styles to your webpages, but since it outputs
audio rather than video it supports a different set of CSS properties. This page
@@ -14,22 +16,98 @@ Setting `speak: never` is not the same as setting `voice-volume: silent` as the
latter still takes up the same ammount of time as it would've to read the text
aloud.
+### Reference:
+#### `speak`
+Usage:
+ `speak: always`
+
+Valid Options:
+ - `always`
+ - `never`
+
+#### `speak-as`
+Usage:
+ `speak-as: spell-out`
+
+Valid options:
+ - `spell-out`
+ - `digits`
+ - `literal-punctuation`
+ - `no-punctuation`
+
## The Voice
You can use the `voice-family` attribute to select a voice either by age/gender/variant
-or by it's name. Just like font-family this'll make a big difference to the look
+or by it's name. Just like font-family this'll make a big difference to the "look"
of your page.
+### Reference
+**Wanted: denote syntax and properly format list**
+#### `voice-family`
+Usage:
+ `voice-family: OPTIONS`
+
+- genders: male female neutral
+- ages: child young old
+
+
## Speaking Style
You can alter the voice you choose by varying it's volume, rate, pitch, range,
and stress. Doing so helps people pay attention, especially if it reinforces the
meaning of your text.
### Keywords & Offsets
-All the speaking style properties provides keywords you can use instead of a
+All the speaking style properties provide keywords you can use instead of a
number. In which case write a number after a keyword to represent an offset from
that keyword.
-## The CSS Speech "Box Model"
+### Reference
+#### `voice-volume`
+Usage:
+ `voice-volume: medium -10dB`
+
+Valid keywords:
+ - `silent`
+ - `x-soft`
+ - `soft`
+ - `medium`
+ - `loud`
+ - `x-loud`
+ - `medium`
+
+#### `voice-rate`
+Usage:
+ `voice-rate: medium -10%`
+
+Valid keywords:
+ - `x-slow`
+ - `slow`
+ - `medium`
+ - `fast`
+ - `x-fast`
+
+#### `voice-pitch`
+Usage:
+ `voice-pitch: medium +10%`
+
+Valid keywords:
+ - `x-low`
+ - `low`
+ - `medium`
+ - `high`
+ - `x-high`
+
+
+#### `voice-stress`
+Usage:
+ `voice-stress: moderate`
+
+Valid keywords:
+ - `strong`
+ - `moderate`
+ - `none`
+ - `reduced`
+
+## Rests, Pauses, and Auditory Cues
On either end of your text you can place an audio cue to identify it, and on
either end of those you can insert additional silence. If two silences are
directly adjacent, the smaller one will be removed.
@@ -40,6 +118,20 @@ it's `pause`.
The user agent stylesheet, for example, uses audio cues to indicate list bullets
and links. And silence functions exactly like whitespace in a visual browser.
+
+### Reference
+> Note: `pause` and `rest` mirror functionality
+> Note: `-before` and `-after` are both offered by the api as well
+#### `pause`
+Usage:
+ `pause: before weak 50ms`
+
+Valid keywords:
+ - `x-weak`
+ - `weak`
+ - `medium`
+ - `strong
+
## Text Generation
Rhapsode supports (some of) the same text generation attributes as visual
browsers, namely:
@@ -51,7 +143,7 @@ browsers, namely:
Though more may be added in the future.
-However unlike visual browsers you can apply the `content` property the element
+However unlike visual browsers you can apply the `content` property to the element
itself to replace it's own children.
---