From 0f61fa288160dc0c605e96418648277f2597a05f Mon Sep 17 00:00:00 2001 From: Adrian Cochrane Date: Thu, 9 Apr 2020 16:01:47 +1200 Subject: [PATCH] Manually linewrap the doc files. --- docs/CSS-Speech-Tutorial.md | 45 ++++++++++----- docs/Designing-for-Rhapsode.md | 50 ++++++++++++----- docs/Hypothetical/Custom-CPU-Design.md | 78 +++++++++++++++++++------- docs/Why?.md | 10 +++- 4 files changed, 134 insertions(+), 49 deletions(-) diff --git a/docs/CSS-Speech-Tutorial.md b/docs/CSS-Speech-Tutorial.md index b51fb19..1488b2c 100644 --- a/docs/CSS-Speech-Tutorial.md +++ b/docs/CSS-Speech-Tutorial.md @@ -1,30 +1,48 @@ -**Wanted:** Guidance on creating a great audio theme. Maybe based on voice acting or public speaking theory. +**Wanted:** Guidance on creating a great audio theme. Maybe based on voice acting +or public speaking theory. -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 provides an overview of these properties. +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 +provides an overview of these properties. ## Should it be spoken? -You can use the `speak` property to determine whether an HTML element should be read aloud or not, and the `speak-as` property to determine how it reads digits and/or punctuation. +You can use the `speak` property to determine whether an HTML element should be +read aloud or not, and the `speak-as` property to determine how it reads digits +and/or punctuation. -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. +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. ## 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 of your page. +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 +of your page. ## 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. +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 number. In which case write a number after a keyword to represent an offset from that keyword. +All the speaking style properties provides 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" -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. +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. -The inner pauses are called the element's `rest` and the outer ones are called it's `pause`. +The inner pauses are called the element's `rest` and the outer ones are called +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. +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. ## Text Generation -Rhapsode supports (some of) the same text generation attributes as visual browsers, namely: +Rhapsode supports (some of) the same text generation attributes as visual +browsers, namely: * `counter-reset` * `counter-increment` @@ -33,9 +51,10 @@ Rhapsode supports (some of) the same text generation attributes as visual browse Though more may be added in the future. -However unlike visual browsers you can apply the `content` property the element itself to replace it's own children. +However unlike visual browsers you can apply the `content` property the element +itself to replace it's own children. --- * [CSS3 Speech Module](https://drafts.csswg.org/css-speech-1/) (Retired W3C Note) -* [MDN on CSS Counters](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Lists_and_Counters/Using_CSS_counters) \ No newline at end of file +* [MDN on CSS Counters](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Lists_and_Counters/Using_CSS_counters) diff --git a/docs/Designing-for-Rhapsode.md b/docs/Designing-for-Rhapsode.md index aa72385..d0b5450 100644 --- a/docs/Designing-for-Rhapsode.md +++ b/docs/Designing-for-Rhapsode.md @@ -1,41 +1,65 @@ ## 1. Write Semantic (X)HTML5 -Use *changes* in Rhapsode's voice to *enhance* the communication of your text, that'll help people pay attention to it. To do so start by making meaningful use of the (X)HTML5 tags, and then (if you want) you can get more specific with Rhapsode-specific CSS. At the very least provide good links. +Use *changes* in Rhapsode's voice to *enhance* the communication of your text, +that'll help people pay attention to it. To do so start by making meaningful +use of the (X)HTML5 tags, and then (if you want) you can get more specific with +Rhapsode-specific CSS. At the very least provide good links. -If you've got quotes, marking them with `` or `
` tags rather than quote marks will render much more clearly in Rhapsode. Rhapsode will then render these in a new voice, while visual browsers will still render them as the appropriate quote marks for your language. +If you've got quotes, marking them with `` or `
` tags rather than +quote marks will render much more clearly in Rhapsode. Rhapsode will then render +these in a new voice, while visual browsers will still render them as the +appropriate quote marks for your language. ## 2. Declare Your Page's Language -If Rhapsode knows what language your page is written in, it can alter some of the phrases it inserts to match (not that it does yet). To do so use the `lang` or `xml:lang` attributes on the root `` element. +If Rhapsode knows what language your page is written in, it can alter some of +the phrases it inserts to match (not that it does yet). To do so use the `lang` +or `xml:lang` attributes on the root `` element. This mostly just applies if you've got forms on the page. ## 3. Don't Rely on JavaScript -Rhapsode doesn't support JavaScript, as it's APIs don't map cleanly to Rhapsode's experience. And because Rhapsode doesn't like it's complexity or security model. +Rhapsode doesn't support JavaScript, as it's APIs don't map cleanly to Rhapsode's +experience. And because Rhapsode doesn't like it's complexity or security model. -As such if your pages break when JavaScript's disabled, they'll almost certainly break in Rhapsode. The exception is for simple scripts that alter the style of an existing element, because Rhapsode follows an alternative set of CSS properties. +As such if your pages break when JavaScript's disabled, they'll almost certainly +break in Rhapsode. The exception is for simple scripts that alter the style of an +existing element, because Rhapsode follows an alternative set of CSS properties. ## 4. Avoid Excess Text -Listeners may tune out if you don't get straight to the point and stay on topic. As for styles, it doesn't matter much what you do as long as you're consistant. +Listeners may tune out if you don't get straight to the point and stay on topic. +As for styles, it doesn't matter much what you do as long as you're consistant. ## Navigation There are a couple of additional points when it comes to navigation. **NOTE:** Navigation has not yet been implemented. -### 5. Never Override `:link {cue-before}` -Visitors will be relying on this audio cue to know this is a link they can follow, and override it defeats the purpose of the link. +### 5. Never Override `:link {cue-after}` +Visitors will be relying on this audio cue to know this is a link they can follow, +and override it defeats the purpose of the link. + +In fact, you are not permitted to do so. This still rule is `!important`. ### 6. Don't Rely on Navbar (Or Adjust Styles) -Because excess text can bore the visitor, Rhapsode defaults to not read out your `