D 2011-12-10T23:08:12.405
L plan
P aadf676da7b867de1c0cf515a8995fd17a06414c
U jen
W 12320
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.
<h2>User features</h2>
<h3>Export to standard manuscript format</h3>
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.
<h3>Other output formats</h3>
LaTeX would be nice, to start with.
<h3>Use the data in the YAML section</h3>
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.
<h4>Why</h4>
Because title pages are good.
<h4>What this might look like</h4>
<verbatim>---
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
...</verbatim>
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.
<h3>Non-chapter headings</h3>
EFM should support headings for things which aren't chapters.
<h4>Why</h4>
Books sometimes have prologues, introductions, books, parts, appendices, etc.
<h4>What this might look like</h4>
<pre>Introduction | Why this story is awesome
////////////////////////////////////////
Prologue |
//////</pre>
<h3>Nested block quotes</h3>
<h4>Why</h4>
Because it's a silly thing to not support.
<h4>What it might look like</h4>
<pre>"""
Blah blah de blah blah blah. Or, as blah said:
\"""
BLAH.
"""
"""
</pre>
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.
<h3>Styles</h3>
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.
<h4>Why</h4>
The idea would be to use this for:
* spans of text that will need special formatting, like the telepathic dialog in some novels, or Death's speech in Terry Prachett's Discworld books;
* blocks of text that will need special formatting, such as the stuff the characters are reading in Sophie's World by Jostein Gaarder, or the index cards in Good Omens by Terry Pratchett and Neil Gaiman.
<h4>What it might look like</h4>
Each style could be defined in the YAML section, and then used later.
So, in the YAML section:
<verbatim>
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.
</verbatim>
And then later in the file:
<verbatim>#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.
}
</verbatim>
<h3>Links</h3>
A linking style would connect a section of text being referred to with a
section of text that refers to it.
<h4>Why</h4>
Footnotes and choose-your-own-adventure style stories.
<h4>What it might look like</h4>
Like styles, the different types of links would probably be defined in the YAML section.
<verbatim>styles:
- name: footnote
label: fn
link: true
- name: direction
label: d
desc: A choose-your-own-adventure direction.
link: true
</verbatim>
Then they'd be used later.
<verbatim>
#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.
...
}
</verbatim>
<h3>Comments and typesetting notes</h3>
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.
<h4>Why</h4>
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".
<h4>What it might look like</h4>
Comments could be marked with the initials of people from the YAML section.
<verbatim>Mark pulled out his slkjhfljk.#se[What do you have against vowels?]
[T|Please insert slkjhfljk.jpg here, with caption "Mark's slkjhfljk".]
</verbatim>
<h3>Include statements</h3>
Include statements would let you include one file in another.
<h4>Why</h4>
This way a long story or a novel could be split up into several files.
<h4>What it might look like</h4>
<verbatim>
[I|Chapter1.efmf]
[I|Chapter2.efmf]
</verbatim>
(Here ".efmf" is meant to stand for "efm fragment")
<h3>Bundled files</h3>
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.
<h4>Why</h4>
Because keeping track of all the individual files manually would be a nuisance.
<h4>What it might look like</h4>
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:
<pre>
attach files:
- slkjhfljk.jpg
</pre>
Programs will be able to read the bundle without the user unzipping it.
<h3>Sections</h3>
A story could be divided into sections.
<h4>Why</h4>
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.
<h4>What it might look like</h4>
<verbatim><<
A section!
<<
A sub-section!
>>
>></verbatim>
<h3>Section metadata</h3>
Each section could have data about it.
<h4>Why</h4>
Like sections, this would give EFM the same kind of tools as fancy writing programs, and would let data be preserved in conversions.
<h4>What it might look like</h4>
Tags could be defined in the main YAML section at the start of the story
<verbatim>tags:
- name: subplot
values:
- main quest
- love story
- mystery
- name: status
values:
- not started
- outlined
- rough draft
- finished draft
default: not started</verbatim>
Then, each section could have YAML data at the start of it:
<verbatim><<
---
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...
</verbatim>
<h3>Revisions</h3>
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).
<h4>Why</h4>
This is more make-EFM-useful-for-editing features.
<h4>What it might look like</h4>
<verbatim>
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?]
</verbatim>
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:
<verbatim>
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?]+
</verbatim>
<h3>Versioning</h3>
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."
<h4>Why</h4>
Because I think it would be useful.
<h4>What it would look like</h4>
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).
<h3>Dictionary</h3>
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.
<h4>Why</h4>
So that character names and such won't have red squigglies when someone views the story on a different computer.
<h4>What it might look like</h4>
<pre>---
dictionary:
- unobtanium
- hand.wav.ium
- George.+
...</pre>
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.
<h2>Techy stuff</h2>
<h3>Fixed IDs</h3>
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:
* add fixed ids that they are not using;
* add a fixed id to something which already has one;
* change a fixed id;
* remove a fixed id, unless they are removing the thing to which it is attached;
* count on any data other than a fixed id to remain unchanged by other programs.
<h3>Config files</h3>
Programs can store config files with a story by adding them to the "attach files" list in the YAML section.
<h3>Events</h3>
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.
<h3>C! (or C++)</h3>
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.
Z f1dda3ec5a40ed753433922d01a9b678