The Basics of BLUEPHRASE

Getting Started with BLUEPHRASE

Mastering the essential concepts of shorthand notation

by Joe Honton Sep 24, 2019

This note will teach you the essentials necessary to effectively use BLUEPHRASE and will reveal shorthand techniques that allow you to perform commonly occurring tasks with greater ease.

Parts of a phrase

When writing with BLUEPHRASE, it's natural to regard your composition as just a plain-text file with a few styling marks sprinkled here and there for emphasis and structure. This simplistic view is one of its strengths. But to gain traction on the power of BLUEPHRASE let's be a bit more formal.

To get started, I'll formally define the parts of a phrase. Some of these are required and others are optional. Each basic phrase, container phrase, and term phrase, consists of as many as seven parts, all of them optional:

1. the opening mark
2. semantax
3. attributes
4. compositional text
5. nested phrases
6. graynotes
7. the closing mark

Consider the simplist and most common of all basic phrasing, a paragraph. It has no opening and closing marks because it fills an entire line from left edge to the <Enter> key. The semantax is a p (which is usually omitted). The compositional text is your written sentences. In its simplist form, a basic BLUEPHRASE paragraph looks identical to a plain-text paragraph.

Early that morning, I caught a glimpse of the elusifaun.

						

Next, consider term phrasing which is used to italicize a word.

• The opening mark is two less-than characters <<
• The semantax is an i
• The compositional text is the word being emphasized
• The closing mark is two greater-than characters >>

<<i elusifaun>>

						

Finally, consider container phrasing such as an unordered list.

• The opening mark is a left-curly brace {
• The semantax is ul
• The nested phrases are the list items
• The closing mark is a right-curly brace }

ul {
    elusifaun
    spanovert
}
 
						

Attributes and shorthand

Some phrases need additional information in order to be useful. For example, a hyperlink needs to specify the URL of the page it is linking to. Phrases that need such data obtain it from attributes that you specify immediately after the phrase's semantax. Attributes look like these examples:

*name=deep-sea-creatures    // generic attribute notation
`http://bathypelagic.com`   // sourceref notation
.graph                      // classname notation      
#summary                    // identifier shorthand
^text-align:center          // styling notation

						

Consider a hyperlink phrase that links to "Creatures of the Deep Sea". Hyperlinks are defined using the HTML anchor tag, which has a mnemonic semantax of a. Here's what it might look like within your manuscript using sourceref notation.

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

						

Another type of shorthand is useful for applying CSS classnames to a phrase. Classnames are one way that HTML is connected to CSS. By way of example, let's say that you've defined a CSS style with a classname of "graph", and you want to apply it to an image of a pie chart that you've included. It might look like this using classname notation.

<<img .graph `piechart.png`>>

						

Another way to connect HTML to CSS is with IDs, which have their own shorthand notation. By way of example, let's say you wanted to apply special styling to a section of your composition, and you've defined a CSS style with an identifier named "summary". It might look like this using identifier notation.

section #summary {
    p Elusifaun and spanovert sightings are uncommon.
} 
						

Sometimes you'll want to apply CSS styling to a single phrase, without referencing styles defined with a classname or identifier. You can do this using style shorthand. Here is an example of a heading that has its text centered on the page:

h1 ^text-align:center The strange beauty of ugly beasts

						

Classnames, identifiers, and sourcerefs are the most frequently used shorthand notations, but there are others available for: RDFa attributes, ARIA roles, and junctors. Examples of these are omitted for the sake of brevity.

Here are the shorthand notations recognized by BLUEPHRASE:

Including other files

As your composition grows it may become cumbersome to keep your thoughts organized with ever larger files. At some point you may find it convenient to split your manuscript into smaller pieces.

BLUEPHRASE files are saved with a filename extension of .blue, which behaves for the most part like a plain-text file. This means that you can use standard cut, copy, and paste functionality to easily split your writing into two or more files. Later, when you need to assemble the separate files into a whole document, you can use the BLUEPHRASE !include pragma. Pragmas are instructions to the BLUEPROCESSOR to perform a specific action.

The syntax for doing this is straightforward: simply type !include on a separate line in your document followed by the filename surrounded by grave accents `. Here's what it looks like:

!include `rare-sightings.blue`

						

If your writing is destined for a Web page, rather than a PDF or printed paper, you may want to include JavaScript files. You should do that using the script semantax, rather than !include pragmas. For example, to include a JavaScript file that contains the popular Prism library, you might use something like this:

script `prism.js`

						

If you've used any of the CSS shorthand notations described above, and have saved your selectors, attributes, and values in an external file, you should use link semantax to provide a reference to it in your document. For example, to include the popular Font Awesome CSS file, you might use something like this:

link *rel=stylesheet `font-awesome.css`

						

In addition to the !include, script, and link methods just described, BLUEPHRASE has specialized methods for including substitution variables and enclosures. For brevity's sake, these advanced topics are not discussed here.

Sourceref shorthand

Finally, you may know that HTML uses different attribute names to reference script, link, and img filenames. In contrast, BLUEPHRASE uses sourceref shorthand for all of these, and automatically converts them to the required attribute. Sourceref attributes are used on several other phrases as well. Here is a complete list:

Special characters

Sometimes you may want to type characters that are not found on your keyboard. Because .blue files are saved with UTF-8 character encoding, any Unicode code point can be used without too much fuss: simply find the special characters you need using an Internet search, then copy them into your document using the <Ctrl-V> clipboard paste command. (Of course, if you are writing in a language other than English, and you have an input method editor (IME) on your device, you can use that method as well.)

This copy and paste method does not work so well for some of the special typographic marks, such as partial-width spaces and extra width dashes, because it is hard to distinguish between similar looking characters until they are printed. When necessary, any character can be added to a BLUEPHRASE document using the Unicode sequence symbol. To do this, type a % percent-sign followed by the hexadecimal value for the Unicode code point. For example, the code point for em-dash is 2014. Here's an example showing that:

The Loch Ness Monster %2014 once theorized to be <<i Silurus glanis>> %2014 is in fact just a hoax.

						

Escape sequences

Usually the BLUEPROCESSOR is able to figure out which part of your document is semantax and which are attributes, but every once in a while you'll need to be explicit. If you encounter this, you can force any character to be treated as itself, by typing a reverse solidus (a backslash) \ immediately before the character in question. Here's an example where the letter "a" needs to be escaped because it would otherwise be interpreted as an anchor semantax:

Her imaginative pisci-tale was <<\a harmless flirtation>>.

						

Substitution variables

Sometimes it's useful to use generic variables in your document and have the BLUEPROCESSOR substitute occurrences of the variable with values that you define elsewhere. This is often necessary when including an external file that contains a template of standard stuff. Consider, for example, a website that uses a template file containing the title and keywords for web pages.

Substitution variables are declared and assigned a value anywhere within your manuscript, like this:

$TITLE="Sea Legends and Myths"
$KEYWORDS="rare, fake, made-up"

						

After defining substitution variables, you can use them in your document, or in an included file. Here's how you would use the variables just defined:

head {
    title $TITLE
    meta *name=keywords *content=$KEYWORDS
}

						

Sequencing variables

Another type of variable that you can define and use is a sequencer. They are especially useful for numbering sections of business and technical documents. Sequencers numerically track a sequence of occurrences within your document.

By using a sequencer and increment operator ++ on each section of your work that needs to be numbered, you establish a method for keeping your document in proper numeric order, even if you rearrange sections.

An important attribute to be aware of, is the format attribute. It may be added to a !var pragma, and used to specify several different types of serial sequences. The possibilities are:

By way of example, suppose you want to number the major divisions of your document using digits, and minor divisions using lower-case alphabetic characters. Your document might have something like this:

!var *varname=MAJOR *format=digits
!var *varname=MINOR *format=alpha

section $MAJOR++ Introduction
section $MAJOR++ Types of Creatures
section $MAJOR.$MINOR++ Mythological
section $MAJOR.$MINOR++ Legendary

						

The output emitted by the processor would look something like this:

1 Introduction
2 Types of Creatures
2.a Mythological
2.b Legendary

						

Clones

Another use for the dollar-sign is to clone a phrase. Clones are exact copies of a phrase used in more than one place in your document. They are defined by placing an identifier on an original phrase, and subsequently cloning it by typing that identifier somewhere else in your document.

Clones come in two varieties: inner clones and outer clones. An inner clone copies only the subject matter of the original source phrase. An outer clone copies all of the original source phrase's semantax, attributes, and subject matter.

Inner clones are used by typing the dollar-sign followed by the identifier enclosed in apostrophes '

Outer clones are used by typing the dollar-sign followed by the identifier enclosed in quotation-marks "

Here is an example demonstrating clones, where the phrase identified as #ab is used in the following sentences as both an inner clone and an outer clone.

<<i #ab aquapugs and benthomorts>>

Two oddities of the animal kingdom are $'ab'.
No clear understanding of $"ab" has emerged.

						

Graynotes

As you work on your composition, you'll occasionally reread something and find it awkward or unnecessary. Sometimes you'll be ready to delete a sentence, but hesitate because you think it might have value someplace else.

You can temporarily mask out a portion of your work by enclosing it between graynote delimiters, which are the two stroke sequence /* to mark the beginning of the graynote, followed by the two stroke sequence */ to mark the end of the graynote.

Graynotes remain visible in your .blue file, but are not visible in the converted output.

During the course of your work, you may want to flag an area as being unfinished. Perhaps you are waiting for someone else to produce a graphic or provide a photograph that will accompany your text, but the file you need is not available to you yet. You can use a second form of graynote as a placeholder for these missing pieces. This type of graynote is delimited with the two stroke sequence /? and ?/.

A third type of graynote is the reply. It is formed syntactically the same way as the other two graynotes, but it is intended for use when two or more people are working on a manuscript and they need to exchange editorial remarks with each other about a word or passage. This type of graynote is delimited with the two stroke sequence /+ and +/.

A final type of graynote, the terminal comment, is a graynote shorthand that can only be applied to standard phrases. It is uses the two stroke sequence // without the need for a closing sequence. Everything up to the end of the line will be masked from the converted output.

Each of these graynotes can be "signed" using a special signature mark immediately after the opening delimiter. The signature mark is a full-stop . followed by your name or initials. As an example, you might have an exchange of remarks by the editor and replies by the author using signatures like this:

These creatures have an exoskeleton and a backbone.

/* .ed  Rework this to clarify, are they exo-verts or verta-skels? */
/+ .aut How about skelverts? 
/* .ed  That'll work! */
    
						

Metadata

As you approach the completion of your writing project, there is one final topic that needs to be considered: how you will prepare your manuscript for others to read.

Up to this point, we've been looking a phrases in isolation, getting a firm grasp on how semantax and attributes and other symbolic marks can be used in general and specific ways. You can readily imagine how paragraphs could be assembled into sections, and sections could be arranged into a whole.

But we haven't yet looked at the metadata for your document. If you're familiar with HTML you know that every web page has to have a title and it must be inside the document's head. Both of those are easy enough to write using the BLUEPHRASE notation you've already learned. While you're writing these, it's a good idea to also add a meta phrase for description: this is what search engines will display, together with your page title, when showing results to searchers.

If your target audience will be reading your composition on the Internet (not in a PDF or ebook or printed paper), you should also add instructions specifically for browsers. Since Web browsers may encounter pages written a long time ago, they need to be told how to interpret certain features of your page. The first clue they need is a DOCTYPE, which should be created with the special !doctype html pragma: it tells browsers that your page follows the HTML5 specification. The next clue is the charset UTF-8 instruction, which informs the browser that your page is encoded with variable length Unicode characters. The final clue is the viewport meta tag, which lets browsers running on smart-phones and tablets display your page in the correct size. All of these put together would look like this example:

!doctype html
html {
    head {
        title Weird and Wonderful
        meta *name=description *content='Sea creatures that you have
              never laid eyes on.'
        meta *charset=UTF-8
        meta *name=viewport *content='initial-scale=1'
    }
    body {
    }
}

						

All of these are optional. If you omit the html, head, and body phrases, stand-ins will silently be added by the BLUEPROCESSOR with default values suitable for most situations.