Dev.ej/web app docs

docs/outputs.md

@@ -3,9 +3,22 @@
 One of the main motivations for ReadAlong-Studio was to provide a one-stop-shop for audio/text alignment.
 With that in mind, there are a variety of different output formats that can be created. Here are a few:
 
-## Web Component
+## Simple web deployment
 
-The standard output from ReadAlong-Studio consists of 1) a ReadALong file (XML) and 2) an audio file,
+The default output generated by the CLI's `readalongs align` command and the `www` folder included in the Web Bundle download format from the [Web App](web-app.md) include everything you need to host your ReadAlong on your own server.
+
+Copy the whole folder with all its contents to your web server, and that should work as is on most web servers. The `index.html` provided will generate a page that shows only your readalong.
+
+The elements of the `index.html` can also be copied into a larger page with other contents, or multiple readalongs -- see [Web Component details](#web-component-details) below.
+
+## WordPress deployment
+
+Deploying to WordPress requires our [wordpress plugin](https://github.com/ReadAlongs/Studio-Web/tree/main/packages/web-component/wordpress-plugin) and the snippet generated by our Web or CLI app, which is included in the `readme.txt` file generated in each Web Bundle from the Web App, or in your output folder from the CLI.
+
+## Web Component details
+
+The standard output from ReadAlong-Studio consists of 1) a `.readalong` file in XML, 2) an audio file,
+3) optional image assets, and 4) a sample index.html file bringing it all together,
 which you can mobilize to the web or hybrid mobile apps quickly and painlessly.
 
 This is done using the ReadAlong WebComponent. Web components are re-useable, custom-defined HTML elements that you can embed in any HTML, regardless of which
@@ -25,12 +38,13 @@ Below is an example of a minimal implementation in a basic standalone html page.
         <!-- Here is how you declare the Web Component -->
         <read-along href="assets/sample.readalong" audio="assets/sample.wav"></read-along>
     </body>
+
     <!-- The last step needed is to import the package -->
     <script type="module" src='https://unpkg.com/@readalongs/web-component@^1.4.0/dist/web-component/web-component.esm.js'</script>
 </html>
 ```
 
-The above assumes the following structure:
+The above assumes the following structure, which is the default provided in the Web Bundle generated from the web app:
 
 ```txt
 web
@@ -46,6 +60,8 @@ Then you can host your site anywhere, or run it locally (`cd web && python3 -m h
 
 With `-o html`, the ReadAlongs Studio will output a completely self-contained HTML file that be shared by e-mail and used without requiring any access to the Internet.
 
+This file is also compatible with our [Editor](web-app.md#the-readalong-studio-editor) where you can make further modifications to your readalong.
+
 ## ELAN/Praat files
 
 With `-o eaf` or `-o TextGrid`, the ReadAlongs Studio can output files in the ELAN eaf and Praat TextGrid file formats.

docs/web-app.md

@@ -0,0 +1,63 @@
+# ReadAlong Studio Web Applications
+
+## The ReadAlong Studio Web App
+
+The ReadAlong Studio functionality can now be used both from a CLI (see the rest of this guide) and a web application meant to be as easy to use as possible.
+
+See
+
+ - [ReadAlongs-Studio Web App](https://readalong-studio.mothertongues.org/),
+ - [El Studio de ReadAlong en español](https://readalong-studio.mothertongues.org/es/), or
+ - [L'appli Studio ReadAlong en français](https://readalong-studio.mothertongues.org/fr/).
+
+The usage documentation for the web app can be access by clicking on "Take the tour"/"¡Siga el tour!"/"Visite guidée" button at the top of the page. We encourage you to take this tour on your first visit, or if you have not taken it yet, as it explains all the parts of the process.
+
+### Web app features
+
+The web app supports the most commonly used features of the ReadAlong Studio:
+
+ - recording audio or using pre-existing audio
+ - typing text or using pre-existing text
+ - creating the readalongs
+ - adding translations
+ - adding images
+ - saving the results in the single file Offline HTML format
+ - saving the results in a multi-file Web Bundle for [deployment on a web page](outputs.md#simple-web-deployment)
+
+### Input text format
+
+The input text has to be provided in the same format as for the CLI. As documented by clicking on `? Format` in the Text input box:
+
+ - Each line should ideally contain one sentence, although that is not a strict rule.
+ - Paragraph breaks are indicated by inserting a blank line.
+ - Page breaks are indicated by inserting two consecutive blank lines.
+
+## The ReadAlong Studio Editor
+
+Recently, the team has also added a much requested feature: the Editor, where you can improve the alignments or fix errors in your readalong.
+
+Links:
+
+ - [ReadAlong Studio Editor](https://readalong-studio.mothertongues.org/#/editor)
+ - [L'éditeur du Studio ReadAlong](https://readalong-studio.mothertongues.org/fr/#/editor)
+ - [El editor del Studio de ReadAlong](https://readalong-studio.mothertongues.org/es/#/editor)
+
+### Opening a ReadAlong in the Editor
+
+The Editor can only read the single file Offline HTML format produced by the ReadAlongs Studio.
+
+You can get this file in various ways:
+
+ - By downloading the Offline HTML file format from the ReadAlongs Studio Web App (this is the default format).
+ - If you downloaded a Web Bundle, you will find an Offline-HTML folder in the zip file containing it.
+ - From the CLI, using the `-o html` option to `readalongs align` generates the Offline HTML file.
+
+### Editor features
+
+In the Editor, you can:
+
+ - Fix alignment errors made by the automatic alignment, by dragging word boundaries in the Audio Toolbar at the bottom.
+ - Fix spelling mistakes in your text, by modifying words in the Audio Toolbar at the bottom.
+ - Add/remove/update images and translations in your readalong.
+ - Update your title and subtitle.
+ - Convert your Offline HTML file into the Web Bundle and other export formats.

mkdocs.yml

@@ -24,6 +24,7 @@ nav:
   - Home: index.md
   - Start: start.md
   - Installation: installation.md
+  - The Web App: web-app.md
   - CLI Guide: cli-guide.md
   - CLI reference: cli-ref.md
   - Output Realizations: outputs.md