Mawe file format (v4) #105

mkoskim · 2023-08-07T11:27:47Z

mkoskim
Aug 7, 2023
Maintainer

File structure (v4)

Mawe (.mawe) file format (v4) is following:

<story format="mawe" version="4" name="<name>">
  <head>...</head>
  <export>...</export>
  <body>...</body>
  <notes>...</notes>
  <ui>...</ui>
  <history>...</history>
</story>

It is intended, that one story has (1) one <body>, the draft of your story you are currently working on, and (2) one <notes>, notes covering this particular story, shared by all other possible drafts (versions) you may have for your story.

`<body>` and `<notes>`

Internally, these are called "sections". In previous versions, the topmost element was chapter, now at version 4 it is an act. Acts are list of <chapter> elements, which are lists of <scene> elements, which are lists of paragraphs, <p> elements. Paragraph elements have different names based on their semantics: they can be p (normal text), br (break), comment (comments), synopsis (text descriptions) and so on.

<body>
  <act name="XXX">
    <chapter name="XXX">
      <scene name="XXX">
        <p> ... </p>
        <p> ... </p>
        ...
      </scene>
      <scene> ... </scene>
    </chapter>
    <chapter> ... </chapter>
    <chapter> ... </chapter>
    ...
  </act>
  <act> ... </act>
  <act> ... </act>
  ...
</body>

`<head>`

The (current) story head (story.head) contains meta information about the (current) draft.

Story title

In the file, name located in the main level <story> element. <head> element has title and subtitle elements:

<story name="...">
  <head>
    <title> ... </title>
    <subtitle> ... </subtitle>
  </head>
</story

When parsing file, name is moved to body.head:

story.head = {
  name: ... // Taken from <story> element
  title: ...
  subtitle: ...
  ...
}

The name of the story is its workname. In very early phase, you call your story by some quite obscure names. For example, one of my colleagues name her stories like "blue", "pink", "red", "black". My story worknames are like "Arthur in space", "Bertta 2020" and so on.

Once the story is more complete, you start to think its title, the name which it will be called when published. We still want to retain its early workname. That's why title elements (title and subtitle) are separated.

The rule is that if the story has explicit title, export uses that. If it don't have explicit title, export uses the workname.

Story author

Head has two elements assigned to author: author and pseudonym:

<story>
  <head>
    <author> ... </author>
    <pseudonym> ... </pseudonym>
  </head>
</story

Author is the real author of the story. The main use of pseudonym are writing competitions which require anonymity. So, for the visible author, pseudonym has precendence over author.

Export settings

When exporting a story, we want to know how we separate chapters and scenes. For chapters, there are numerous options:

Numbered: Chapter is exported as a number
Named: Chapter is exported with its name
Numbered & named: Chapter is exported with chapter number and its name
Separated: Chapters are separated by "* * *"
None: Chapters are separated by <br/>

For scenes, there are few options:

Separated: scenes are separated by "* * *"
None: scenes are separated by <br/>

There is one more choice to make, the story type. Story type - document class - can be:

Short story: Short stories don't use page breaks between chapters. This is common if you are participating short story writing competition.
Long story: Long stories get separate title page, and chapters (if they are numbered or named) start at new page.

This information is located to export element:

story.export = {
    type: "long" | "short",
    chapters: "numbered" | "named" | "numbered&named" | "separated" | "none",
    scenes: "separated" | "none"
  }
  ...
}

In the file structure:

<story>
  <export type="..." chapters="..." scenes="..."/>
</story

History

History element stores daily word counts, one entry per day:

<history>
  <words data="YYYY-MM-DD" text="123" missing="123" chars="123"/>
  <words .../>
  ...
</history>

peter88213 · 2024-10-11T06:40:30Z

peter88213
Oct 11, 2024

This seems to be a good step towards an XML file format for interchange.
For documentation and validation, you may want to create a DTD. This can also help, for instance, when deciding which data should be saved as attributes and which as separate XML elements.

So in my first draft, I saved the word count log entries as empty elements with attributes, like you do.
Then I found out that there is no specific attribute type for the date and the word counts, so I had to use the unspecific CDATA, which I wanted to avoid. This is why I eventually went the "yWriter" way and used own elements:

The chapter specification above shows, in contrast, the use of specific attributes.
This is just an example how creating a formal specification makes you think about details.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Mawe file format (v4) #105

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 1 comment

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Select a reply

Mawe file format (v4) #105

mkoskim Aug 7, 2023 Maintainer

File structure (v4)

<body> and <notes>

<head>

Story title

Story author

Export settings

History

Replies: 1 comment

peter88213 Oct 11, 2024

mkoskim
Aug 7, 2023
Maintainer

`<body>` and `<notes>`

`<head>`

peter88213
Oct 11, 2024