Overview

Paradocs (https://yohasebe.com/paradocs) is a paragraph-oriented text presentation system. It is suitable for presenting a large piece of text, typically paragraph by paragraph, while making comments and explanations. With Paradocs, each press of a key or button highlights one sentence after another. This allows the audience to know which particular sentence the presenter is focusing on at the moment.

The creator of Paradocs originally developed it for personal use in an ESL reading class at the university he works at. In reading classes, both teachers and students tend to spend most of their time looking down, which, he thought, was a sad thing. With Paradocs, you can easily prepare presentations for use in class by simply formatting the original text into a "one sentence per line" format. You can use it in conjunction with a remote meeting app such as Zoom to conduct online classes.

Paradocs has multi-lingual text-to-speech (TTS) capability, which uses the Web Speech API of browsers such as Google Chrome, Mozilla Firefox, Apple Safari, and Microsoft Edge, allowing you to choose one of the multiple languages installed on your computer and have the sentence read out for you and your audience whenever you want during your presentation. (The TTS read-aloud function and some other functions cannot be used with Microsoft Internet Explorer.)

The presentation can be used by the user to give an oral presentation. Or, you can have the whole thing presented automatically. Click on the magic wand icon in the upper right hand corner of the screen. From the next fragment of the current slide to the final fragment of the entire presentation, text reading, video playback, etc. will be performed automatically, one after another.

Many of the features of Paradocs rely on the presentation slide creation library Reveal.js developed by Hakim El Hattab. I am truly grateful to him and his collaborators for this wonderful library. The beautiful background wallpaper is provided by Transparent Textures.

Paradocs was developed by Yoichiro Hasebe. This site uses Google Analytics to analyze traffic, but does not collect user information through any other mechanism. The text data entered into this system is converted into a presentation and sent back to the user's browser, but is not stored on the server.

Documentation

1. Key Bindings

Many available during the presentation can be performed using the mouse, but can also be operated using the keyboard.

TIPS

I recommend Logitech Wireless Presenter R400/R800, a presentation pointer device. It allows you to use the physical buttons to move between items while presenting in Paradocs and to start/stop text-to-speech, video, and audio.

2. Basic Concepts

Sentence

Sentences are separated by a single line break (↩). In a paragraph, they are treated as adjacent elements, each of which are highlighted one after the other. The automatic sentence-segmentation feature allows you to automatically split the text into sentences according to the language used (English, Japanese, etc.). To perform automatic sentence-segmentation, prefix the text with !! at the beginning of the text.

Paragraph

A block made up of multiple sentences is called a paragraph. A paragraph is represented by a block consisting of multiple lines, each of which has a single sentence.

Block

A block is separated by two or more consecutive line breaks ↩↩; a single block can have more than one element. A block composed of multiple sentences is specifically called a paragraph.

Slide

A slide can also be called a "page." Slides are separated by a single line break after four or more hyphens (----↩ or- - - -↩). A single slide can have more than one block.

How to describe a paragraph

Multiple sentences are arranged vertically with a line break to form a paragraph.

----
Sentence #1 
Sentence #2  
Sentence #3 
----

With the automatic sentence splitting feature, the above can be written as follows:

----
!! Sentence #1 Sentence #2 Sentence #3
----

To perform automatic sentence splitting, prefix the text with !! at the beginning of the text. Also, each sentence must end with a sentence delimiter, such as a period or some other punctuation mark.

How to arrange multiple blocks in a slide

To place more than one block on a single slide, place a single line of space between blocks.

----
Block #1
Block #2  

Block #2 
Block #2 
----

Create multiple slides (pages)

A slide can also be said to be a page. A single slide can contain multiple blocks.

----
Slide #1
----
Slide #2
----
Slide #3
----

3. Types of Blocks

The following is a description of the various types of blocks.

Headings

You can create different levels of headings. The headings will be displayed in the selected accent color.

----
# Heading 1 

## Heading 2 

### Heading 3 
----

Regular Paragraphs

A regular paragraph is created by describing a block with one sentence per line.

This is regular paragraph. 
Sentences in static text are highlighted when focused. 
They are printed in grey when not focused. 

In a normal paragraph, pressing a key will move the highlight from sentence to sentence.The slide frame automatically scrolls when the text cannot fit on it at the same time.

Static Paragraphs

To create a static paragraph, place a vertical bar sign and a space at the head of each sentence that makes up the paragraph.

| This is static paragraph. 
| Sentences in static text are not highlighted 
| They are always printed in black. 

or

| This is static paragraph. 
  Sentences in static text are not highlighted 
  They are always printed in black. 

When you are viewing a static paragraph, the per-sentence highlighting is turned off. It is important to note that a static paragraph does not automatically scroll when it does not fit on the slide.

Unordered Lists

This is the so-called bullet point format. To describe the elements of an unordered list, put an asterisk and a space at the beginning of each line.

* Unordered list item 1
* Unordered list item 2 
* Unordered list item 3 

The list scrolls automatically when all the elements don't fit on the slide.

Ordered Lists

This is the format of a sequential list. To describe the elements of this type of list, put a number/letter, a period, and a space at the beginning of each line.

1. Ordered list item 1
2. Ordered list item 2
3. Ordered list item 3

a. Ordered list item 1
b. Ordered list item 2
c. Ordered list item 3

The list scrolls automatically when all the elements don't fit on the slide.

N.B. It is not possible to specify the first number/letter in the list.

Numbered Blocks

You can create a block with a specified number. This is useful when you want to present formulas or exercises in your presentation.

365. The number in a numbered block will be printed only once; 
     the left-hand side of the text can have multiple lines 
     the lines are aligned nicely

N.B. The white spaces to the left of the second and subsequent lines in the above example are important.

4. Decoration and Annotation

Text Decoration

Text segments can be bolded, italicized, underlined, or highlighted.

Italic:    orange *strawberry* apple
Bold:      orange **strawberry** apple
Underline: orange _strawberry_ apple
Highlight: orange ==strawberry== apple

Showing Notes and Pop-up Images

It is possible to display short text in notes that are separated from the body text. Notes are created using braces and the note command. In addition to the text notes, you can create an image popup by specifying the file URL with the image command.

This is part of main text. {note: This is a note}
This is also part of main text. {note: This is another note}
You can also add a pop-up image. {image: url_to_your_image_file.(png|jpg|gif)}

N.B. Notes and pop-up images are available in "regular paragraphs" and "unordered/ordered lists" (not available in static paragraphs). You cannot display notes and pop-up images when the automatic sentence-segmentation function is used. The curly brackets { } and the text inside will be ignored.

Quizzes

Using curly brackets and the quiz command, you can create a quiz in such a way that you initially keep the text hidden from your audience and reveal it at the appropriate time.

| In a static context, words and phrases in {curly brackets}
| will be rendered as {quize items} overlayed by an opaque box.

N.B. When creating a quiz, you must use a static paragraph or a static ordered/unordered list.

5. Embedding Media Files

You can embed images, videos, and audio into your slides.

Embed Images

You can specify the URL of an image file in PNG/JPG/GIF format uploaded on the web and display it on the slide. The image will be enlarged as much as possible.

image: url_to_your_image_file.png

or

img: url_to_your_image_file.png

N.B. To display an image on a slide, make sure that the above command is the only block on that slide. If multiple blocks are described, the images themselves are not displayed, but links to the images are used.

TIPS

If you want to embed your own diagrams, you can use Google Drawings and can paste image links generated by its Publish to the web function. Or you can also use Mermaid Live Editor and get Link to SVG to embed business diagrams such as flowcharts or Gantt charts.

Embed YouTube Video

You can specify the URL of the YouTube video and display it on the slide. The video will be enlarged as much as possible.

youtube: https://www.youtube.com/watch?v=Ks-_Mh1QhMc

or

yt: https://www.youtube.com/watch?v=Ks-_Mh1QhMc

You can specify the start and end points in the URL of the youtube video. It is possible to specify them by the number of seconds that have elapsed since the beginning of the video. Add the options to the URL in the &start=x&end=y format. The following will play from 12 minutes 27 seconds (x=747) to 12 minutes 55 seconds (x=775) of the video.

youtube: https://www.youtube.com/watch?v=RKK7wGAYP6k&start=747&end=775

You can also specify the start time and the end time by "hour:min:sec" notation, which may be easier for many users.

youtube: https://www.youtube.com/watch?v=RKK7wGAYP6k&start=12:27&end=12:55

N.B. To display a YouTube video on a slide, make sure that the above command is the only block on that slide. If multiple blocks are described, the videos themselves are not displayed, but links to the videos are used.

Embed MP4 Video

You can specify the URL of a video file in MP4 format uploaded on the web and display it on the slide. The video will be enlarged to the (nearly) entire slide page.

video: url_to_your_video_file.mp4

You can specify the start and end points in the URL of the video. Note that each is represented by the number of seconds that have elapsed since the beginning of the video. Add the options to the URL in the #t=x,y format. The following will play from the very beginning of the video (x=0) and stop it after 5 seconds (y=5).

video: url_to_your_video_file.mp4#t=0,5

N.B. To display an MP4 video on a slide, make sure that the above command is the only block on that slide. If multiple blocks are described, the videos themselves are not displayed, but links to the videos are used.

Embed MP3 Audio

You can specify the URLs of audio files in MP3 format uploaded on the web and display them on the slide.

audio: url_to_your_audio_file.mp3

You can specify the start and end points in the URL of the mp3 video. Note that each is represented by the number of seconds that have elapsed since the beginning of the audio clip. Add the options to the URL in the #t=x,y format. The following will play from the very beginning of the audio clip (x=0) and stop it after 5 seconds (y=5).

audio: url_to_your_audio_file.mp3#t=0,5

N.B. It is possible to have multiple audio files in a single slide. The slide page automatically scrolls when all the blocks do not fit on the current viewport.

6. Additional Features

Text-to-Speech

Sentences in regular paragraphs can be played back with a text-to-speech engine available in your browser. The available languages and audio variations vary by OS and browser.

When TTS is available for highlighted content, a speaker icon appears in the upper right hand corner of the presentation screen. Click on this icon or press the . key on the keyboard to play the TTS voice. You can stop playback by clicking the button or hitting the key again.

Sticky Note

You can show your audience what comes to mind during your presentation by writing it in a sticky note.

You can show or hide the sticky note by clicking its icon at the top left of the presentation screen. The contents of the sticky note will be retained even if the slide changes.

Laser Pointer

You can change shape/color of your mouse cursor from the ordinary one to a laser-pointer-like colored dot. Click on ● at the top left of the screen to toggle modes.

The color of the modified mouse pointer is determined by the selection for the "accent color" in the setting panel.

Automatic Presentation

Click on the magic wand icon in the upper right hand corner of the screen. From the next fragment of the current slide to the final fragment of the entire presentation, text read-aloud, video playback, etc. will be performed automatically, one after another.