Update of "plan"
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Artifact ID: 3b43d0069dc974252d98dd49738584e656e57d89
Page Name:plan
Date: 2011-12-10 23:08:12
Original User: jen
Parent: aadf676da7b867de1c0cf515a8995fd17a06414c
Content

This is a list of planned features and changes. There are two main sections: the first is features that would matter to EFM users, and the second is features and changes that would mostly affect developers.

User features

Export to standard manuscript format

Currently, the export uses a lot of default RTF formatting (eg a proportional font), and changes it does make to formatting are non-manuscript-y (eg italics rather than underlines).

Given its purpose, it would probably make more sense for the export to be in standard manuscript format. There could be an option to export to the current non-manuscript-y format instead.

Other output formats

LaTeX would be nice, to start with.

Use the data in the YAML section

Currently, the YAML sections only allow you to put some data about your story in the EFM file. The converter doesn't use the data for anything. However, it could use it to create a title page in the RTF file.

Why

Because title pages are good.

What this might look like

---
title: Spike's Awesome Story

people:
 - &jp
   name: Jen Pollock
   writing as: Spike McAwesome-Cool
   initials: jp
   role: author
   email: jen@jenpollock.ca
   address: |
      1234 Imaginary St
      Imaginary City, Canada    A1A 1A1
   phone: 555-555-5555
   fixed id: 1

 - &se
   name: Someone Else
   initials: se
   role: agent
   fixed id: 2
...

This format would let there be multiple authors (for collaborations), and it would give the converter all the info it needs to create a title page. It also can include info about an editor, so that the editor's initials can be used to mark comments and revisions.

Non-chapter headings

EFM should support headings for things which aren't chapters.

Why

Books sometimes have prologues, introductions, books, parts, appendices, etc.

What this might look like

Introduction | Why this story is awesome
////////////////////////////////////////

Prologue | //////

Nested block quotes

Why

Because it's a silly thing to not support.

What it might look like

"""
Blah blah de blah blah blah.  Or, as blah said:
\"""
BLAH.
"""
"""

Here, the existing escape-a-quote-to-make-it-an-opening-quote syntax is used to mark the second set of quotes as opening a new block quote, rather than closing the open one. This may not be the clearest thing ever. I'm certainly open to suggestions about this. On the other hand, this isn't a feature that I expect would get used that often.

Styles

This feature would let writers mark some text as needing special formatting. It would include a place to describe why the text is being marked, but not any way to actually apply formatting.

Why

The idea would be to use this for:

What it might look like

Each style could be defined in the YAML section, and then used later.

So, in the YAML section:

styles:
 - name: telepathy
   label: t
   desc: Telepathic dialog.  Should maybe be in bold or something.
 - name: letter
   label: l
   desc: Letter from one character to another.

And then later in the file:

#t{Have you read my letter yet?}

#t{Not yet.  I'll read it now, ok?}  She got out the letter.

#l{
Dear protagonist,

I have a huge crush you.  Which is really awkward, because you don't seem to like me and are telepathic.  This is why I'm leaving.
}

Links

A linking style would connect a section of text being referred to with a section of text that refers to it.

Why

Footnotes and choose-your-own-adventure style stories.

What it might look like

Like styles, the different types of links would probably be defined in the YAML section.

styles:
 - name: footnote
   label: fn
   link: true
 - name: direction
   label: d
   desc: A choose-your-own-adventure direction.
   link: true

Then they'd be used later.

#d+pier{
You adjust your hat#fn>hat{} and walk over to the pier.  The water certainly looks dark enough to hide a sea monster.

#fn+hat{It has three corners.}

#d>ship{Hire the whaling vessel}

#d>boat{Buy a row boat}
}

#d+boat{
The boat looks a little rickety, but it's within your budget.
...
}

Comments and typesetting notes

Comments would provide a way for a writer and editor to communicate.

Typesetting notes would be like comments, but would be specially marked, so that a program could show them to the typesetter automatically while skipping the other comments.

Why

Comments are necessary for editing, and will be needed if EFM is ever to be a useful format for more than the first draft.

Typesetting notes would be used for things like "insert such-and-such a picture here".

What it might look like

Comments could be marked with the initials of people from the YAML section.

Mark pulled out his slkjhfljk.#se[What do you have against vowels?]

[T|Please insert slkjhfljk.jpg here, with caption "Mark's slkjhfljk".]

Include statements

Include statements would let you include one file in another.

Why

This way a long story or a novel could be split up into several files.

What it might look like

[I|Chapter1.efmf]

[I|Chapter2.efmf]

(Here ".efmf" is meant to stand for "efm fragment")

Bundled files

A bundled file would have an efm file and all the files it includes or references bundled together, probably in a zip file with the file extension changed.

Why

Because keeping track of all the individual files manually would be a nuisance.

What it might look like

The bundled file could have the extension ".efmz", which would stand for "efm, zipped".

It could be possible to have other files automatically added to the bundle by listing them in the story YAML data:

attach files:
 - slkjhfljk.jpg

Programs will be able to read the bundle without the user unzipping it.

Sections

A story could be divided into sections.

Why

To provide the sort of structuring tools found in fancy writing software like Scrivener, yWriter, Liquid Story Blender, etc.

A fancy EFM editor could show the sections as a tree. And conversions from fancy-writing-software formats to EFM could preserve the existing tree structure.

What it might look like

<<
A section!

<<
A sub-section!
>>
>>

Section metadata

Each section could have data about it.

Why

Like sections, this would give EFM the same kind of tools as fancy writing programs, and would let data be preserved in conversions.

What it might look like

Tags could be defined in the main YAML section at the start of the story

tags:
 - name: subplot
   values:
    - main quest
    - love story
    - mystery

 - name: status
   values:
    - not started
    - outlined
    - rough draft
    - finished draft
   default: not started

Then, each section could have YAML data at the start of it:

<<
---
title: Vision
description: >
  The main character has a mysterious vision, inspiring her to set out
  on her quest.
sub-plot: main quest
status: rough draft
...

Jane fell into an uneasy sleep...

Revisions

Some way for insertions, deletions, and highlights to be marked. The marking would likely include the initials of the reviser and a revision number (so multiple revisions could be marked at once).

Why

This is more make-EFM-useful-for-editing features.

What it might look like

Mark heard a noise in the hall.  He pulled out his
- slkjhfljk.                     #se1
-+ *slkjhflhk*[What do you have  #+se1 -jp2
-+ against vowels?].
+ slkjhflhk, which he had got    #jp2
+ from the khxvlkj, a species
+ that didn't use vowels.
+ [Better?]

This would be marked up by a program, not manually. There might also be a program to display it nicely.

Previous draft of what this might look like:

Mark heard a noise in the hall.  He pulled out his #se1=slkjhfljk.=#jp2=#se1+*slkjhflhk*[What do you have against vowels?].+=#jp2+slkjhflhk, which he had got from the khxvlkj, a species that didn't use vowels.[Better?]+

Versioning

EFM should include a utility to save different versions of a story in a "history file", compare any two versions from the history, and mark up the differences between any two versions. It should know how the versions are related. It should be able to mark versions with comments, such as "this is the version I submitted to that contest in February."

Why

Because I think it would be useful.

What it would look like

Haven't much designed what the interface to do this would look like.

It would probably use fossil for the actual version handling (which is the main reason why EFM uses fossil).

Dictionary

This would be list of words that are in the story that aren't in most dictionaries, such as character names. It could also include hyphenation data.

Why

So that character names and such won't have red squigglies when someone views the story on a different computer.

What it might look like

---
dictionary:
 - unobtanium
 - hand.wav.ium
 - George.+
...

The dots in "handwavium" show hyphenation points. "Unobtanium" has no hyphenation points marked, so it will be hyphenated in the default way (whatever that may be). "George" has a hyphenation point marked at the end only, which indicates it should not be hyphenated. It also has a "+", indicating that the spelling is case-sensitive.

Techy stuff

Fixed IDs

Programs may add an positive integer "fixed id" to the metadata for a person, style, or tag. This way they can store settings related to that person, style, or tag, even if the name or label is later changed by some other program. Any such settings should be stored in a separate config file, which should be added to the "attach files" list.

If there are any fixed ids, there must also be a "highest fixed id" which is equal to the highest fixed id assigned so far. The next fixed id added must be higher than the current highest, and the highest must be updated.

Users should never change or delete a fixed id, unless they are deleting the person/style/tag to which it is attached.

Programs should never:

Config files

Programs can store config files with a story by adding them to the "attach files" list in the YAML section.

Events

Instead of parsing the entire file into a tree, the parser should probably emit events (ie chapter header encountered, new paragraph started), and the rtf-writing bit should handle them. This would make re-using the parser easier, and it would avoid reading the whole file into memory needlessly.

C! (or C++)

At some point, I'd like to convert the guts of the converter into a library that could be more easily reused. This will probably involve using C or C++ instead of Python, so that it can be easily reused from a wider variety of programming languages.

With this in mind, the current Python implementation is basically a prototype.