Premium Desktop Software

Read Write Doc

RWDOC - Rediscover the beauty of HTML

by Read Write Tools Dec 16, 2019

Read Write Doc is a distraction-free desktop app built on top of BLUEPHRASE. It is used for creating declarative templates and authoring HTML documents.

Why bother? Well, let's face it. HTML is not pretty.

Reading an HTML document is not for the faint-hearted. All those tags clutter things up. Fishing the author's words out of the tag soup is a challenge. And writing an HTML document is no better. Who wants to subject themselves to that torturous mix of <tag>...</tag> for every highlighted word in their composition. It's slow and clumsy.

I'll show you how BLUEPHRASE cleans up the mess, and makes declarative templating and content authoring less of a chore.

Getting rid of tag soup

Take a look at this sample, written using BLUEPHRASE notation. Notice how the semantic meaning is still obvious, but the tags have mostly disappeared. The remainder is called semantax, which in this case is h1, article, ul, b, blockquote, h2, and a.

h1 Mythical Sea Creatures

article {
    Elusifaun and spanovert sightings are uncommon.
    ul {
        <<b elusifaun>> — a furtive water mammal, seen occasionally on moonlit nights.
        <<b spanovert>> — a marine reptile with a periodic, seven year rhythm.
    } 
    blockquote {
        Early that morning, I caught a glimpse of the elusifaun. 
    } 
}

h2 See Also
<<a `http://bathypelagic.com` Creatures of the Deep Sea>>
						

When Read Write Doc is switched into preview mode, we can see how the browser renders it.

And in the source code view, we see how our BLUEPHRASE manuscript was compiled into HTML. It's straightforward and matches our expectations. Notice though, how the compiler generated the list items <li>...</li> and paragraphs <p>...</p> without requiring the author to be explicit. This is called implied semantax.

<h1>Mythical Sea Creatures</h1>

<article>
    <p>Elusifaun and spanovert sightings are uncommon.</p>
    <ul>
        <li><b>elusifaun</b> — a furtive water mammal, seen occasionally on moonlit nights.</li>
        <li><b>spanovert</b> — a marine reptile with a periodic, seven year rhythm.</li>
    </ul>
    <blockquote>
        <p>Early that morning, I caught a glimpse of the elusifaun.</p>
    </blockquote>
</article>

<h2>See Also</h2>
<p><a href='http://bathypelagic.com'>Creatures of the Deep Sea</a></p>
						

Declarative Templating

What I've demonstrated, in this first simple example, is an HTML fragment. We can expand it into a full document by enclosing it in a template.

Here's a bare bones template to get started. It provides a title, description, and keywords which search engines will use, and a link to an external CSS style sheet to enhance the document's appearance, and a JavaScript file for scripting. I'm using substitution variables to make the enclosure generic. This way, it can be used for other documents too. Also, note the all important !target-matter pragma, which is the insertion point for our HTML fragment.

html {
    head {
        title $TITLE
        meta *name=description *content='$DESCRIPTION'
        meta *name=keywords    *content='$KEYWORDS'
        link `my-website.css`  *rel=stylesheet *type=text/css
    }
    body {
        !target-matter
    }
    script `my-website.js`
}
						

In order to wrap our sample fragment with this enclosure, we amend the original sample with an !enclosure pragma specifying the filename for the enclosure, and we identify a selector that triggers its use. In this case I've arbitrarily chosen the identifier #story as the target matter to be wrapped.

!enclosure #story `my-enclosure.blue`
$TITLE="Mythical Sea Creatures"
$DESCRIPTION="Elusifaun and spanovert sightings are uncommon."
$KEYWORDS="sea creatures, elusifaun, spanovert, bathypelagic"

main #story {        
    h1 $TITLE
    
    article {
        $DESCRIPTION
        ul {
            <<b elusifaun>> — a furtive water mammal, seen occasionally on moonlit nights.
            <<b spanovert>> — a marine reptile with a periodic, seven year rhythm.
        } 
        blockquote {
            Early that morning, I caught a glimpse of the elusifaun. 
        } 
    }
    
    h2 See Also
    <<a `http://bathypelagic.com` Creatures of the Deep Sea>>
}    
						

We can examine the combined result when we switch Read Write Doc to HTML mode. Our document fragment is wrapped by our simple enclosure into a fully compliant HTML document ready for the internet.

<html>
    <head>
        <title>Mythical Sea Creatures</title>
        <meta name=description content='Elusifaun and spanovert sightings are uncommon.' />
        <meta name=keywords content='sea creatures, elusifaun, spanovert, bathypelagic' />
        <link href='my-website.css' rel=stylesheet type=text/css />
    </head>
    <body>
        <main id=story>
            <h1>Mythical Sea Creatures</h1>
            
            <article>
                <p>Elusifaun and spanovert sightings are uncommon.</p>
                <ul>
                    <li><b>elusifaun</b> — a furtive water mammal, seen occasionally on moonlit nights.</li>
                    <li><b>spanovert</b> — a marine reptile with a periodic, seven year rhythm.</li>
                </ul>
                <blockquote>
                    <p>Early that morning, I caught a glimpse of the elusifaun.</p>
                </blockquote>
            </article>
            
            <h2>See Also</h2>
            <p><a href='http://bathypelagic.com'>Creatures of the Deep Sea</a></p>
        </main>
    </body>
    <script src='my-website.js'></script>
</html>
						

Shorthand notation

BLUEPHRASE uses shorthand notation to specify attributes.

You've already seen one type of shorthand in action. It's the backtick delimiters `` used with the !enclosure pragma, the link to a CSS style sheet, and the anchor tag a hyperlink destination. BLUEPHRASE understands these to be filename references or href attributes or src attributes based on their context within the document.

Another type of shorthand is a named attribute, which uses asterisk notation. You may have noticed its use in the meta tag *name and *content attributes.

Two other commonly used shorthand symbols will be familiar to anyone that knows CSS. They are hashtag notation # for identifiers, and fullstop notation . for classnames. For example, we could modify our sample fragment to make use of #story-title, .bullets and .pull-quote to look something like this.

h1 #story-title $TITLE

article {
    $DESCRIPTION
    ul .bullets {
        <<b elusifaun>> — a furtive water mammal, seen occasionally on moonlit nights.
        <<b spanovert>> — a marine reptile with a periodic, seven year rhythm.
    } 
    blockquote .pull-quote {
        Early that morning, I caught a glimpse of the elusifaun. 
    } 
}

h2 See Also
<<a `http://bathypelagic.com` Creatures of the Deep Sea>>
						

And the compiled HTML output would be as expected:

<h1 id=story-title>Mythical Sea Creatures</h1>

<article>
    <p>Elusifaun and spanovert sightings are uncommon.</p>
    <ul class=bullets>
        <li><b>elusifaun</b> — a furtive water mammal, seen occasionally on moonlit nights.</li>
        <li><b>spanovert</b> — a marine reptile with a periodic, seven year rhythm.</li>
    </ul>
    <blockquote class=pull-quote>
        <p>Early that morning, I caught a glimpse of the elusifaun.</p>
    </blockquote>
</article>

<h2>See Also</h2>
<p><a href='http://bathypelagic.com'>Creatures of the Deep Sea</a></p>
						

Product comparison

Read Write Doc is more than just a BLUEPHRASE wrapper. It also has syntax highlighting, HTML source code mode, spell-checking, PDF exports, and preview style-sheets. And BLUEPHRASE has much more than just declarative templating and shorthand notation. Together, they can be used to compose sophisticated documents for print or Web.

If your needs are simple, and you want a no-frills notepad-style templating app, you may be happy with Read Write Note. It has the same distraction-free authoring interface, and full BLUEPHRASE capabilities, including enclosures and shorthand notation.

You can also use Read Write View, a free app that lets you switch between BLUEPHRASE and browser preview mode. If you don't need syntax highlighting, you can create plain-text .blue files in your favorite text editor, and compile them into HTML with Read Write View.

License and availability

See Read Write Tools Pricing to learn about 21-day trials and licensed versions. See Read Write Doc to register and download now.

Read Write Doc is available for Windows, Mac and Linux.