Highland new syntaxes

[Paul Rankin]

After perusing all the new proposed syntaxes in the Highland betas, I
think the group/list might like to look over these and consider some of
the strengths and weaknesses....

(These news syntaxes are up to release "Muttley".)


-- Directives

Here are some directives:

{{%m}}
{{toc}}
{{toc: }}
{{header}}
{{header: }}
{{header: %none}}
{{header: %p %pp}}
{{header: %## %p.}}
{{include: file.fountain}}
{{include: file.png}}
{{title}}
{{%title}}
{{header: %title}}
{{what about this}}
{{%m}}
{{m}}
{{%p}}
{{header: %##}}
{{%##}}

It's difficult to see which of these are valid and which aren't, as the
example directives included in the Highland release notes currently
don't offer much consistency or clues about how the syntax breaks into
component parts.

I think that following Stu's recent reiteration that Fountain should be
simple and look as much like a script (screenplay, stageplay, etc.) as
possible, I think that directives are very complex and the relative
merits need to be really weighed up with a constant view towards
simplicity over complex functionality.

Regarding the header/footer format directives {{header: FORMAT}} and
{{footer: FORMAT}}, this introduces *two distinct syntaxes* -- one
within the other. While I can understand that the header/footer contents
need to change mid-document, I can't see any real-world use case where a
writer needs to change the format of these mid-document. Even in very
complex documents, the header/footer formats seldom change, and so, if a
writer is preparing such a complex document, perhaps Fountain is not the
right tool. (MS Word, LaTeX, Apple Pages, InDesign or ReStructeredText
are all more suitable for this kind of complexity.)

One way directives could be greatly simplified is if {{key}} is always
viewed as placeholder *key*, replaced with a *value* (the text inserted)
where there is always a hopefully intuitive relationship between key and
value. e.g.

title: The 50ft Figure of Speech
    {{title}}
=>
The 50ft Figure of Speech

Here the key-value relationship is specified externally but clear: I've
told Fountain what the title is, then I'm inserting the title. (Although
the above IRL use is probably very rare, this is just an atomistic
example for simplicity's sake.)

{{include: file.fountain}}
=>
/* contents of file.fountain */

Here the key-value relationship is specified internally and clear, as it
replicates the use of the colon we've already seen with metadata where I
use it to tell Fountain what something is. Perhaps this could also be
used to include image files too?

{{include: alien-language.png}}

I think the main thing is that simplicity needs to come from
a consistent and intuitive syntax.


-- Text Highlighting

From release notes:

> In addition to bold, italics, and underlining, you can now highlight.
> [...] For example, “This is a +very good+ sentence.” [...]

> Highlighting is available in both Fountain and Markdown documents, and
> follows the same rules as bold or italics. The markup will only apply
> to paragraphs, and doesn’t extend across paragraph breaks. (This
> prevents accidentally highlighting an entire document by forgetting to
> close a highlight tag.)

I think highlighting is great. Very easy to tell a cowriter to "just
+add pluses+ around text."

Edge-case:

+Is this paragraph completely highlighted because I did not close
the highlight tag?

Edge-case:

+!WHAT ABOUT
This one, where I have forced action?


-- Term Lists

> JOSH :: Ze Frank
> NORMAN :: Ben Falcone

I find this really great. Imminently useful for screenplays, stageplays,
etc. It's reminiscent of Markdown. I can't see any edge-case where this
could cause a problem or any confusion.


-- Right-aligned text

> Add a > to the end of a line and it will be shifted all the way to the
> right margin.
>
> Put me on the edge!>

This is problematic. It's quite uncommon and I'd wager unintuitive to
have syntax characters at the end of a text line, and there are a few
cases where the writer will end a line with >

URLs are commonly written as <https://secure.government.com>

Also...

terminal-01% > access main program
Access denied.
terminal-01% > access main security
Access denied.
terminal-01% >

I'm ambivalent about the need for right-aligned text in a script, but
regardless I think there is a better syntax to achieve this. e.g.

>| Put me on the edge!

| Put me on the edge!

>> Put me on the edge!