Getting started with ReAdable Human Format


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.

Usage

Step 1. Create your readable document in any text editor

Create a learn-khmer.txt file in a notepad, or learn-khmer.read.red file if you use VSCode to benefit from syntax highlighting with Red extension.
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. That's all you need to know as business user except one more thing: if ever your text contains any word containing "Red" (red is ok) you must replace this string by "Red" (in a future evolution, we'll do it for you.) If you are a webdesigner or a developer, you may have to deal with html entities encoding:

4.1 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 red escape character ^, you must html encode it with ^ (see https://www.freeformatter.com/html-entities.html)


4.2 you can use html tags like <br> or <a href='...'></a> inside text. If you want to show html tags litterally, you must encode them (use an online encoder like https://mothereff.in/html-entities)

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 separate script file learn-khmer.red for 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, install Red and optionally VSCode with Red extension

Install only older version, for windows: 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.

Faq

How to add a subscription form to ReAdABLE human format document

This is how easy it is to add, for example, this mailchimp subscription popup form:

 <script type="text/javascript" src="//downloads.mailchimp.com/js/signup-forms/popup/unique-methods/embed.js" data-dojo-config="usePlainJson: true, isDebug: false"></script><script type="text/javascript">window.dojoRequire(["mojo/signup-forms/Loader"], function(L) { L.start({"baseUrl":"mc.us20.list-manage.com","uuid":"363b40a4db743ba4ef5a555a3","lid":"f99b32278c","uniqueMethods":true}) })</script> 

just create a text block with the mailchimp code inside:

 .text: {
<script type="text/javascript" src="//downloads.mailchimp.com/js/signup-forms/popup/unique-methods/embed.js" data-dojo-config="usePlainJson: true, isDebug: false"></script><script type="text/javascript">window.dojoRequire(["mojo/signup-forms/Loader"], function(L) { L.start({"baseUrl":"mc.us20.list-manage.com","uuid":"363b40a4db743ba4ef5a555a3","lid":"f99b32278c","uniqueMethods":true}) })</script> } 

the readable source of this guide contains an even more complex subscription form:

 Subscribe: [ .title: {Subscribe to our mailing list} .sub-title: {To receive update news once a month} .text: {Just click below: <br><br><button id='open-popup' style='background:red;color: white;cursor:pointer;font-size: 14px;text-align: center;text-decoration: none;border: none;border-radius: 3px;padding: 13px 32px;font-family:Helvetica Neue,Arial,Helvetica,Verdana,sans-serif' >Subscribe to our mailing list</button> } .text: { <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script> <script type="text/javascript" src="//s3.amazonaws.com/downloads.mailchimp.com/js/signup-forms/popup/embed.js" data-dojo-config="usePlainJson: true, isDebug: false"></script> <script>
function showMailingPopUp() { require(["mojo/signup-forms/Loader"], function(L) { L.start({"baseUrl":"mc.us20.list-manage.com","uuid":"363b40a4db743ba4ef5a555a3","lid":"f99b32278c"}) }) document.cookie = "MCPopupClosed=; expires=Thu, 01 Jan 1970 00:00:00 UTC";
}; document.getElementById("open-popup").onclick = function() {showMailingPopUp()};
</script> }
] 

How to add Google Analytics ReAdABLE human format document

Currently adding script into html header is not accessible for content writer. It should be added later during the process of generating the complete html page: we'll see how to in the next future tutorial.

Subscribe to our mailing list

To receive update news once a month

Just click below: