{{ }} syntax

[John August]

Highland 2 beta testers will notice that we've shifted from using [[square brackets]] to {{curly braces}} for meta information about the file. 

This helps keep square brackets clear for their original purpose of letting writer leave notes for themselves in the flow of the script.

Square brackets:

• Bourne races through the Guangdong metro station [[check if they actually have a subway]], the police on his tail.
  

Curly braces:

• {{header: %p of %pp}}
• {{footer: %none}}
• {{%m}} (new syntax for markers)
• {{include: sparrow.fountain}}
  

By distinguishing between these two elements, it's easy to programmatically check for notes (or remove them). 

Applications that don't use metadata can safely ignore anything in curly braces without omitting any user-created content.

[Stu Maschwitz]

Very handy. Thanks for the details John! Slugline will get on board with this syntax as well.

-Stu

[Paul Rankin]

 

On Fri, 27 May 2016, at 03:12 AM, John August wrote:

Highland 2 beta testers will notice that we've shifted from using [[square brackets]] to {{curly braces}} for meta information about the file.

 

Not sure if this is the right way to go here. Michael Russo already has a simple and elegant solution to including files. See: https://github.com/mjrusso/mountain

 

This includes a file:

 

[[ include: file.txt ]]

 

These includes a note:

 

[[ remember to include: dogs, cats, bunnies ]]

 

A file-resolve failure includes a note:

 

[[ include: good stuff ]]

[[ include: non-existent-file.txt ]]

 

This syntax is backwards compatible and people are already using it. I think you can see the discussion of edge cases in the GitHub issues.

 

This helps keep square brackets clear for their original purpose of letting writer leave notes for themselves in the flow of the script.

 

 

Hmm I don't think "original purpose" is relevant. A note should be whatever is inside square brackets. A writer should be free to use them however.

 

Michael used them as file include directives for his Mountain program. I've used them as cross-file bookmarking system. Maybe someone is using them as a shopping list. Who knows.

 

Curly braces:

 

• {{header: %p of %pp}}
  
• {{footer: %none}}
  
• {{%m}} (new syntax for markers)
  
• {{include: sparrow.fountain}}
  

 

I find this confusing. Why introduce complexity?

 

The header and footer formats can be in the top-of-file metadata with:

 

title: My Script

author: John Doe

header-format: %p of %pp

 

The include directive is better solved with Michael's Mountain syntax.

 

And as for bookmarks, these work across files, and are backwards compatible:

 

[[ 3c0bc1be ]]

 

[[ 2016-05-27 14:51:42 ]]

 

I encourage a change of course here.

 

[John August]

 

This syntax is backwards compatible and people are already using it. I think you can see the discussion of edge cases in the GitHub issues.

Backwards-compatability is laudable goal. Progress is an equally important goal, particularly for something as young as Fountain. I think curly braces strike the best balance of both, for all the reasons I explained above.

The use of square brackets for metadata is understandable; it was the only choice we offered in the original spec. If we had launched with curly braces for metadata, I'm sure Mountain would have used that.

Mountain and others can keep using square brackets if they want to. No documents will break. 

To say that square brackets are better, or better suited to the task, to me mostly comes down to, "I was already using square brackets." So were we. But as we looked at how we were using them, we realized that we were making the experience significantly worse for users by mixing up content and metadata. That's what prompted us to change.

 

The header and footer formats can be in the top-of-file metadata with:

 

title: My Script

author: John Doe

header-format: %p of %pp

Headers and footers need to be able to change over the course of the document. For example, it's common to renumber pages in screenplays (e.g. 74A). In other documents, you may wish to add the chapter to the header, except in the introduction.

Inline metadata makes this possible. At the start of a section, the writer can choose to change the header or footer.

Again, none of this was important in early versions of Fountain. But as more and more screenwriters use Fountain, we keep encountering situations where we have to say, "There's no way to do that in Fountain. But yeah, there should be."

I don't think I'm going to convince you of the wonders of curly braces for metadata -- and that's fine! Nothing will break. I just wanted you to have the heads up that Highland (and now Slugline) will be using them going forward in order to build things screenwriters are asking for.

 

[mjrusso]

FWIW, I’m really happy to see first-class support for metadata in Fountain, regardless of the syntax.

In the long run I do believe that introducing `{{}}` will be better for Fountain and its users than the status quo, for a few reasons, but especially because:

> …we realized that we were making the experience significantly worse for users by mixing up content and metadata.

An alternative is to *officially* overload `[[]]` for metadata purposes (e.g. notes that start with `<identifier>:` are metadata) — but I believe that the note-vs-metadata dichotomy will be easier to explain to users when the markup is completely different. (I’d also expect to see note-vs-metadata handled more consistently between tools/apps with this new syntax, since it is unambiguous.)

That being said, there’s a few things I think that we should think about — 

Standardization

Are we going to standardize (certain) types of metadata, so that behaviour is consistent between tools?

Marking “Regions” in the Document

All of the current examples can be thought of like “self-closing tags" in HTML:

- {{header: %p of %pp}}

- {{footer: %none}}

- {{%m}} (new syntax for markers)

- {{include: sparrow.fountain}}

However, it is conceivable that you will want to be able to explicitly “wrap” a region in the document with certain metadata (which necessitates the ability to explicitly close a metadata tag).

For example, here’s a contrived example from Mountain:

[[reference: script.fountain]]

FADE IN:

> FADE OUT.

[[/reference]]

Here, the metadata is understood to apply to everything between the opening and closing `reference` “tag”.

(I’m just using Mountain as an example here. I totally get why Highland went with a simpler {{include:}} — my point is that we should really think about whether we want to bless this non-self-closing-tag approach, because it is *extremely* powerful for all sorts of use cases that haven’t been thought up yet — but at the cost of increased document complexity.)

Michael.

[John August]

Standardization

Are we going to standardize (certain) types of metadata, so that behaviour is consistent between tools?

I think moving towards standards should be the goal, while acknowledging that individual tools and apps need to be able to experiment to see what's genuinely useful. 

Some types of metadata will really only apply in specific use cases, and that's fine. But a few will probably end up being used by lots of different app, so coming to a standardized format will help everyone. 

Marking “Regions” in the Document

However, it is conceivable that you will want to be able to explicitly “wrap” a region in the document with certain metadata (which necessitates the ability to explicitly close a metadata tag).

A great example is marking a section of a document as revised. In screenplays, this is usually indicated by asterisks in the right-hand margin. But what is the equivalent in Fountain?

We already have some tags that mark off regions, like *bold* and [[notes]]. 

So is the best choice to load up an operator (say, %) so that we can indicate %this section has been changed?% 

Or should we do something more akin to HTML, perhaps on the order of {{rev}}this is new text{{/rev}}? 

I can make arguments for both. I think we're more likely to come upon a good solution by not pre-deciding. By trying a bunch of things, we're more likely to come up with a way that works well in actual use.

This Google group feels like a good place to share our experiments and discuss options.

[Paul Rankin]

On Sat, 28 May 2016, at 07:04 AM, John August wrote:

Headers and footers need to be able to change over the course of the document. For example, it's common to renumber pages in screenplays (e.g. 74A). In other documents, you may wish to add the chapter to the header, except in the introduction.

 

This is interesting. Is this a move towards page-locking and revisions?

 

I don't think I'm going to convince you of the wonders of curly braces for metadata -- and that's fine!

 

I'd like to think I'm a convincible guy.

 

I see Michael is all in for this syntax, and since I kinda saw him as the symbolic father of this file-inclusion thing in Fountain, if he likes the curly syntax better then so do I.

 

[Paul Rankin]

On Wed, 1 Jun 2016, at 11:09 PM, mjrusso wrote:

FWIW, I’m really happy to see first-class support for metadata in Fountain, regardless of the syntax.

 

In the long run I do believe that introducing `{{}}` will be better for Fountain and its users than the status quo, for a few reasons

 

Cool. Really glad you chimed in Michael :)

 

However, it is conceivable that you will want to be able to explicitly “wrap” a region in the document with certain metadata (which necessitates the ability to explicitly close a metadata tag).

 

For example, here’s a contrived example from Mountain:

 

[[reference: script.fountain]]

 

FADE IN:

 

> FADE OUT.

 

[[/reference]]

 

 

Here, the metadata is understood to apply to everything between the opening and closing `reference` “tag”.

 

(I’m just using Mountain as an example here. I totally get why Highland went with a simpler {{include:}} — my point is that we should really think about whether we want to bless this non-self-closing-tag approach, because it is *extremely* powerful for all sorts of use cases that haven’t been thought up yet — but at the cost of increased document complexity.)

 

The curly syntax reminds me a bit of the Liquid template engine: https://shopify.github.io/liquid/

 

Let's ignore that Liquid uses both {{ this }} and {% this %} for a moment, it has a nice explicit wrapping by prefixing the opening tag with "end", e.g.

 

    {{ if this }}

    content

    {{ endif }}

 

It's probably similar in all the other curly-brace template languages that I don't know about too.

 

The only thing is that failing to terminate an if statement in Liquid will result in a compiler error, and the writer me doesn't want to deal with compiler errors...

[Paul Rankin]

I'm just taking the first stab at implementing the directives syntax in Emacs and just after a bit of clarification...

If I have a script with:

title: Acceleration

credit: written by

author: Keanu Reeves

sidekick: Harry

and I write the following:

KEANU

Damnit {{sidekick}} we need more... {{title}}!

should I get

KEANU

Damnit Harry we need more... Acceleration!

when exporting?

(Also, I'm sure another Fountain app has something very similar to this but I can't remember which.)

[Stu Maschwitz]

Is that really what the {{metadata}} element is for? I never imagined it being used that way.

-Stu

[Paul Rankin]

Stu Maschwitz <pro...@prolost.com> on Mon, 01 Aug 2016 18:22 -0700:

> Is that really what the {{metadata}} element is for? I never imagined
> it being used that way.

Probably not IRL... I'm just trying to isolate the most basic
semantic use. I've seen examples that are semantically complex, like
{{toc}} or {{header: %p of %pp}} so I just wanna whittle it down so I
can do the codes the right way.

Also, is this

> title: Acceleration
> credit: written by

called metadata and this

> {{title}}

called a directive......?

[Paul Rankin]

Wait sorry I do have an IRL use-case I'm already using....

I have a title template, so the writer can change the way the title page
exports to HTML/LaTeX/text/PostScript/etc. say from

> {{title}}
>
> {{credit}}
>
> {{author}}

to maybe

> _{{title}}_
> "{{episode}}"
>
> {{credit}}
> {{author}}

without needing to edit the export templates of each format. There's a
contact template too.