Getting started with ReAdable Human Format

Step by step guide

ReAdABLE human format is meant to be very easy to read, to write and to generate.
We eat our own dog food: this step by step guide has been generated with ReAdABLE human format. Source is available here and proves complex document can be written easily like with inclusion of custom subscription form.

Index

- Getting Started (this article)
- Faq
- Timeline (Use case)
- Templating (Coming soon, subscribe to our mailing list to get notified.)

Usage

Step 1. Create your readable document in any text editor

Let's suppose you need to write a requirement for a learning website in ReAdABLE human format, below is a contrived example:

you can copy and paste readable content from below:


title: "Learn Khmer"
sub-title: "Khmer consonants"

Intro: [
     .text: {Description is:}
     .quote: {Learn Khmer
It's easy!} ] logo: [ .title: "Logo" .text: {logo is not available yet} image: %img/logo.png ; without . prefix for image, it won't be output ] menu: [ .title: {Home | Lessons | Contact | About} ] Content: [ .title: "Kor, Khor, Kour, Khour" .text: "ក Kor" .text: "ខ Khor" .text: "គ Kour" .text: "ឃ Khour" .title: "Gnor, Chor, Chhor, Chour" .text: "ង Gnor" .text: "ខ Chor" .text: "ឆ Chhor" .text: "ជ Chour" ] Footer: [ .sub-title: {Copyrigth Lépine Kong} ]

Rules are very few and simple:

1. a block of paragraphs is delimited with brackets [] and has a label like "Content:" 

2. Document title and sub-title are not enclosed by brackets
3. tags like .title, .text, .quote, .image are prefixed with dot . otherwise it acts as meta-tags. For example image without dot prefix a meta-tag (see logo). Same result if it is an unknown tag (in the future you'll be able to define custom tags).
4. text is either enclosed by double quotes "" or curly braces {}. Curly braces allow multi-lines contrary to double quotes.
4.1 for integrating a subscription form see faq
That's all you need to know as business user.
If you are a webdesigner or a developer, you may have to deal with html entities encoding:
4.2 for markdown output to github, you can use refinement for example code/javascript to create specific styling for code tag.
4.3 for direct html output you can use html tags like <br> or <a href='...'></a> inside text. If you want to show html tags litterally, you must either wrap with <xmp></xmp> tags or encode them (use an online encoder like https://mothereff.in/html-entities)
4.3 you can generally embed braces inside braces without the need to escape character except if it is ambiguous in that case use ^ to prefix a curly brace, for example ^}. If you need to show character ^ which is red escape character, you must html encode it with &#94; (see https://www.freeformatter.com/html-entities.html)
4.4 one more thing: if you are a Red developer and you want to use html proxy pattern, if ever your html content contains any word containing "Red" (red is ok) you must replace this string by "&#82;ed": that's the way the Red interpreter works with html content (in a future evolution, we'll automate the replacement for you.)

Step 2. add inline code to generate output or create a build script

There are 2 main ways to do so.

Quick way is to create a readable document wrapped with:


Red []
article: [
    ...
]
do https://readable.red
.markdown-gen ; to generate markdown 
.html-gen ; to generate html
    


Or create a script for build, learn-khmer.red in our example:


article: load %learn-khmer.read.2.red ; article is mandatory name
do https://readable.red
.markdown-gen ; to generate markdown 
.html-gen ; to generate html
    

.markdown-gen or .html-gen or markdown-gen or html-gen will work. It's our convention to prefix with . to visually differentiate a function or command from a variable name.

Step 3. If not done yet, download Red

Install is straightforward: download and run the exe.
Install only older version only - at the moment readable library is not compatible with latest version; for windows use this link: https://static.red-lang.org/dl/win/red-063.exe

Preferably install VSCode with Red extension


on Windows, run this command for VSCode to be able to run Red in terminal:

red.exe --cli

If ever you have only notepad, launch Red and type:


cd %your-project/path
do %learn-khmer.red
    

Step 4. Run your build script created :

Under VSCode, Right-Click and select:

Run Red Script

or press Key:

F6

Step 5. Check outputs:

There should be 2 output files:
- one markdown file
- one html file

Remark that the html generated is only partial (no htm header). This is on purpose so as to separate presentation from content. Next time, we'll see how to build the complete html page.

Subscribe to our mailing list

To receive update news once a month

Just click below: