Jim's
Tutorials

nick says

As of right now, I've settled on calling the thing that I'm building TweeTeX. When I refer to Twee\(\TeX\), I'm referring to the language and compiler that I'll be specifying and writing for Plan.

the basics

The basic component of a Twee/Twine story is the passage. A passage contains text to be read, and may contain a link to other passages, but it isn't necessary (although it is necessitated by the "hypertext" part of "hypertext literature"). Passages are the nodes of our larger graph, and links are the connections. The story is the entire graph. Before we think about any greater functionality, we must be able to handle the creation of stories, passages, and links.

a story should also contain some metadata, namely:

• author
• title (may default to the name of the actual file if not specified)
• starting passage (this may default to the first passage defined)
• IFID (kind of like ISBN numbers for hypertext works)

example of potential TweeTeX syntax

I have two examples for each syntax I'm considering.

\title{My Story}
\author{Nick Creel}
\ifid{0CA8C7C5-F219-4B1B-A3A8-45710F389818}
\start{Starting Passage}

\passage{Starting Passage}
This is some text in the first passage
\link{Second Passage}{This link goes to the second passage}

\passage{Second Passage}
This is some text in the second passage.

\documentclass{twee-story}
    \title{My Story}
    \author{Nick Creel}
    \ifid{0CA8C7C5-F219-4B1B-A3A8-45710F389818}
    \start{Starting Passage}
    \begin{document}
        \begin{passage}{Starting Passage}
            This is some text in the first passage
            \link{Second Passage}{This link goes to the second passage}
        \end{passage}
        \begin{passage}{Second Passage}
            This is some text in the second passage.
        \end{passage}
    \end{document}

grammar

I started playing around with writing a grammar, which has led me to a few questions for you. First, here's what I have so far for this really simple case.

<story> :== <preamble> <passage>+ 
<preamble> :== <id> <macro>*
<id> := "\ifid{" [\w]+ "}"
<macro> :== "\" <command> [ "{" <argument> "}" ]*
<command> :== "link" | "start" | "author" | "title"
<passage> :== "\passage" { "{" <argument> "}" } <text> 
<char> :== [^\\\{\}]
<argument> :== <char>+ | <macro>
<text> :== <char>* {<macro>} {<text>}


    -- lexer --
    COMMAND     (including backslash)
    LEFTCURLY
    RIGHTCURLY
    CHARACTERS

    --- parser ---
    ... recursive stuff ...

(* end text at next passage 
https://stackoverflow.com/questions/7124778/how-to-match-anything-up-until-this-sequence-of-characters-in-a-regular-expres *)

(* i want to recognize all text between passage delims without throwing out
potential macros/expressions within the paragraph text *)

I think the trickiest thing about this is the text following the passage. I'm trying to think of a way to match text following a \passage tag without accidentally swallowing up any following passages as text...traditionally, items in a LaTeX document like sections are started by making some declaration (like \section{Section Title}), and these declarations do not have an ending delimiter. Usually, they do not end until:

• another section begins
• the document ends

This syntax is pretty similar to the twee syntax, where a passage is denoted by ::Passage Name, and everything following the passage name is considered passage text, until another passage is reached or the document ends.

There's another syntactic element in LaTeX that limits some parts of the document to different "sections", such as the \begin{} ... \end{}. This is used to create proofs, arrays, abstracts, enumerated lists, equations, figures... they don't seem to define anything like a page, but are included within particular sections, and create an environment for writing or doing a particular task.

I originally thought that I should use some construct like \begin{passage}{}...\end{passage} but I'm not sure if this is the simplest way to handle the passages, nor am I sure I like the way it looks. It would be helpful to have them as delimiters to avoid the lexer being too greedy and recognizing the declaration for the next passage as part of the current packages' text, I think? Thirdly, I think it might give the unhelpful illusion that my code is actually valid LaTeX input. Perhaps excluding things that are only relevant to LaTeX files (document class, \begins and \ends} would help make it more clear that I am not writing a LaTeX to Twee compiler.

It seems like there is the ? construction for making a lazy regular expression to match all the text following a \passage declaration as text and stopping when it reaches the next \passage in the file. I am in the process of writing a lexer to test this out. I'm wondering, though, if this requires some consideration in the grammar, or if it's kosher to just specify this in a regular expression during the lexer stage.

Note: It seems that the regex [\w\s]+?(?="\passage") uses a "lookahead assertion", which means that it will only match <text> if the [\w\s]+ is followed by another \passage. This isn't exactly what I want...Is there a way to have this be the first thing tried? as long as it is, I think all the cases where passage is followed by anything should be captured, but there will always be one passage that isn't followed by a \passage declaration, and I want this to be recognized as a passage...