From 2481b8c0a5030f0a1f5e7093072929f043bcb081 Mon Sep 17 00:00:00 2001 From: Adrian Cochrane Date: Thu, 9 Apr 2020 15:49:07 +1200 Subject: [PATCH] Merge wiki into main repo. --- docs/CSS-Speech-Tutorial.md | 41 +++++++++++++ docs/Designing-for-Rhapsode.md | 41 +++++++++++++ docs/Home.md | 5 ++ docs/Hypothetical/Custom-CPU-Design.md | 82 ++++++++++++++++++++++++++ docs/Why?.md | 13 ++++ 5 files changed, 182 insertions(+) create mode 100644 docs/CSS-Speech-Tutorial.md create mode 100644 docs/Designing-for-Rhapsode.md create mode 100644 docs/Home.md create mode 100644 docs/Hypothetical/Custom-CPU-Design.md create mode 100644 docs/Why?.md diff --git a/docs/CSS-Speech-Tutorial.md b/docs/CSS-Speech-Tutorial.md new file mode 100644 index 0000000..b51fb19 --- /dev/null +++ b/docs/CSS-Speech-Tutorial.md @@ -0,0 +1,41 @@ +**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. + +## 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. + +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. + +## 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 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. + +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. + +## Text Generation +Rhapsode supports (some of) the same text generation attributes as visual browsers, namely: + +* `counter-reset` +* `counter-increment` +* `counter-set` +* `content` + +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. + +--- + +* [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 diff --git a/docs/Designing-for-Rhapsode.md b/docs/Designing-for-Rhapsode.md new file mode 100644 index 0000000..aa72385 --- /dev/null +++ b/docs/Designing-for-Rhapsode.md @@ -0,0 +1,41 @@ +## 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. + +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. + +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. + +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. + +## 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. + +### 6. Don't Rely on Navbar (Or Adjust Styles) +Because excess text can bore the visitor, Rhapsode defaults to not read out your `