A primer for effectively using BLUEPHRASE

BLUEPHRASE Essentials

This note will teach you the essentials necessary to effectively use BLUEPHRASE. It will also reveal techniques that enable you to perform certain commonly occurring tasks with greater ease using shorthand notation.

Once you've gained a little bit of experience writing documents with basic BLUEPHRASE, you'll want to round out your knowledge with a few additional concepts. This will enable you to work on typical writing tasks, such as adding attributes to phrases, using external files, dealing with special characters, embedding internal notes to yourself, and supplying metadata about your finished work for others.

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 to add emphasis to words and to organize sentences into sections. 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, we'll need to define the parts of a phrase: some are required, others are optional; some are visible, others are not.

Each phrase, whether it's standard, subordinate, or grouped, consists of as many as seven parts:

1. the opening mark
2. optional semantax
3. optional attributes
4. optional subject matter
5. optional phrases that it encloses
6. optional graynotes
7. the closing mark.

Consider the simplist and most common phrase, a paragraph. Formally, the opening mark is the left edge of the document; the semantax is omitted but implied to be p; the subject matter is your written sentences; and the closing mark is the invisible carriage return added when you pressed the <Enter> key. (We'll leave attributes and graynotes alone for a bit.) So in its simplist form, a standard BLUEPHRASE paragraph looks identical to a plain-text paragraph.

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

Next, consider a subordinate phrase which is used to italicize a word. Formally, the opening mark is a << left-facing chevron; the semantax is an i; the subject matter is the word being emphasized; and the closing mark is a >> right-facing chevron.

<<i elusifaun>>

Finally, consider a grouped phrase, such as an unordered list. Formally, the opening mark is a { left-curly brace; the semantax is ul; the subject matter is omitted; the other enclosed phrases are the li phrases with implied semantax; and the closing mark is a } right-curly brace.

ul {
    elusifaun
    spanovert
} 
					

Most phrase parts are optional, with the major exception being the opening and closing marks required by subordinate and grouped phrases.

Attributes and shorthand

Some phrases need to be supplied with explicit data in order to be useful. For example, a hyperlink needs to specify the URL of the page it is linking to. Phrases that need explicit data obtain it from attributes that you provide within your document, which you type immediately after the phrase's semantax. Attributes have four parts:

1. a transitional symbol
2. an attribute name
3. an assignment connector, and
4. the attribute value.

Consider a hyperlink phrase that links to "Creatures of the Deep Sea". (Hyperlinks are defined using the HTML "anchor" tag, which has a mnemonic of a.)

The transitional symbol for generic attributes is an * asterisk, so that comes immediately after the a semantax; hyperlinks specify URLs in an href attribute, so that comes next; the assignment connector is an = equals sign; and finally the attribute value is the URL itself "http://bathypelagic.com". The entire phrase with semantax, attribute and subject matter looks like this:

<<a *href="http://bathypelagic.com" Creatures of the Deep Sea>>

Attributes can be shortened in many cases by using special shorthand notation, and in practice, the four-part generic attribute syntax just described is seldom needed. The shorthand notation for the previous example, would be to replace the four parts of the href attribute with the special sourceref shorthand, which is simply ` grave-accents surrounding a URL. The previous example using this notation becomes:

<<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, and in practice, classnames are frequently used. 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 in your composition using a subordinate phrase. The semantax for images is the mnemonic img, and the shorthand notation for classnames is a . full-stop. The entire phrase with semantax, classname shorthand, and sourceref shorthand is:

<<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". The semantax for sections is simply the whole word section, and the shorthand notation for identifers is a # hash tag. The entire phrase, with semantax, identifier shorthand, curly brace opening/closing marks, and enclosed phrases looks like:

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 the typographic style shorthand. The shorthand notation for styles is the ^ caret symbol. This shorthand is similar to four-part generic attributes, except the assignment operator is a : colon. Furthermore, it is often necessary to enclose the CSS value itself in apostrophes or quotation marks in order to avoid confusion with the other shorthand notation. Here is an example of a heading that has its text centered on the page:

h2 ^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: adding Resource Description Framework attributes (RDFa) to a phrase; adding Accessible Rich Internet Application (ARIA) roles to a phrase; and bi-directionally interlinking two or more phrases with junctors. Examples of these are omitted for the sake of brevity.

Here are the shorthand notations recognized by BLUEPHRASE:

In addition to these, it's also possible to define your own shorthand notation, when you need to, but that is a specialized topic and will not be discussed here.

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 a BLUEPHRASE !include instruction.

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`

The !include instruction, is formally termed a pragma. Pragmas are instructions to the BLUEPROCESSOR to perform a specific action. There are many other pragmas, which for brevity's sake are not discussed here.

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.

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

As you've learned, BLUEPHRASE uses symbolic endophrasing, which inverts the typical instruction embedding inside-out, so instead of enclosing phrases within instructions you do the opposite: you embed instructions within phrases. 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, because your subject matter isn't distinguishable from instructions. If you encounter this, you can override the interpretation of any semantax or shorthand directive and force it to be the character you typed. You do this 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>>.

Substitutions, sequencers and clones

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 defined using the !var pragma. You use this pragma by choosing an arbitrary name for your variable, and supplying the substitution string with the value attribute. Here are a couple of examples:

!var *varname=TITLE *value='Sea Legends and Myths'

!var *varname=KEYWORDS *value='rare, fake, made-up'

After defining substitution variables, you can use them in your document, or in an included file, using the $ dollar-sign symbol. Here's how you would use the variables we just defined:

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

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. The use of sequencers is especially convenient in the early stages of your writing when you are just beginning to flesh out the outline of your work. At that stage, you may be reordering, inserting, and removing sections of your work and want to automatically renumber those sections after each change.

Sequencers are defined with the same !var pragma that we used for substitution variables. You may omit the value attribute and it will default to "0". After the variable is defined, you can use it in your writing in tandem with the increment operator. This will instruct the BLUEPROCESSOR to add "1" to the sequencer's current value, and emit the result to the output that it creates. By using the sequencer and increment operator on every 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 your !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 BLUEPROCESSOR would look something like this:

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

Another use for the $ dollar-sign symbol, 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 clones, copies only the subject matter of the original source phrase. An outer clones 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 .blue 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 some place 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 an arbitrary sequence of letters. 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 smartphones 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.

Summary

• Phrases are syntactically composed of opening and closing marks, semantax, attributes, subject matter, other phrases, and graynotes.
• Attributes are applied to phrases using shorthand notation placed immediately after the semantax.
• External files can be referenced with !include, script, and link using sourceref shorthand.
• Special characters can be entered using the Unicode sequence symbol.
• The escape sequence can be used to prevent a character from being interpreted as semantax or shorthand notation.
• Substitutions and sequencers are defined with the !var pragma.
• Clones make copies of source phrases using identifiers.
• Graynotes are internal remarks for the author's use, and are not visible in the final output.
• Metadata needs to be defined if your target is a Web page, but may be omitted if your target is print media.

bobbie@mail.readwritetools.com

bobbie