-
Notifications
You must be signed in to change notification settings - Fork 5
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Twee] Twee Documentation #2
Comments
re: the Special Tag Names. |
Thoughts1) Notation. While it's legal to do so, I think we should generally consider it bad form to snuggle passage header components. For example:
I think we should also talk about avoiding various metacharacters within the components. For example, you generally want to avoid using the tag block metacharacters ( 2) Neither of the special names sections (Special Passage Names, Special Tag Names) mention that names are case sensitive. It would also probably be a good idea to only refer to the names in their proper case and, possibly, also only within code tags—i.e. 3) The Special Passage Names section lists 4) The Special Passage Names section pretty much only covers Twine/Twee 1.4+ and their story formats. 5) The Special Tag Names section erroneously says:
In most compilers there is no intentional ordering outside of load order—maybe all compilers, I'm unsure if Twee2 imposes an order. 6) The |
Updated from @tmedwards's feedback. Now includes more details and examples from Tweego and Twee2 documentation. NotationThe notation is written as a series of three parts for the header of each passage:
The content of a passage continues until the next sigil of a passage is found or the input ends with at least a single empty line between passage headers. Example Twee Notation:
Special Passage NamesMany compilers understand and process certain case-sensitive keywords differently. The following is a common set of reserved passage names.
|
Just to clarify, there are a lot of things that are "unnecessary" in TweeGo depending on your workflow, but it does honor the script and stylesheet tags within a twee source file in the expected way. (So those two special tags are different from the long list of Twee2-only special tags.) I also think the references to UserStylesheet and UserScript should be retained; stories exported to twee from Twine 2 with Entweedle include these passages, making them special enough to mention. In general the specialness of special passages varies from compiler to compiler, from story format to story format, and between Twine versions. It is not, for example, the case that all Twine 2 story formats ignore StoryAuthor, so the statement that it will be ignored during compilation in Twee 2 is a bit misleading. (Twee2 has a history of throwing away such passages, but I believe that's fixed now.) I think it would be useful to distinguish between special passages and tags from Twine 1 that are used by Twine 2-oriented twee compilers to compensate for the changes in Twine 2 that moved some data out of special passages (e.g., Start, StoryTitle, UserScript/Story JavaScript.) and those that were only ever special passages in the eyes of a story format (e.g., StoryMenu). |
Personally I believe that the name of these two 'special' passages should be changed to StoryStylesheet and StoryScript (or even StoryJavaScript) respectively, that way they are more consistent with their associated names in the Twine 2.x application, and because User (eg. end-user) isn't a term that most Authors / Developers would call themselves. |
I also believe that the url for Entweedle (the Twee exporter that is the closest thing to an official one and which is apparently responsible for coining these names) as documented on its own site should be changed to the https version supported by the Twinery. But I don't have high hopes for either. Should Twine 2 ever produce Twee output, the specced approach should be used, whatever it will be. StoryStylesheet and StoryJavaScript sound good to me. For the record, Twee 2 coined yet more names for this purpose: StoryCSS and StoryJS. |
While we work (I hope) toward some sort of specification at some point, I am proposing creating documentation for Twee as it currently exists.
The following is a revised version of most current draft of the Twee entry in the Twine Cookbook and consists of information pulled from Tweego's documentation and off the Twine wiki.
Notation
The notation is written as a series of three parts for the header of each passage:
The content of a passage continues until the next header of a passage is found or the input ends with at least a single empty line between passage headers.
Example Twee Notation:
Special Passage Names
Some compilers understand and process certain keywords differently. The following is a common set of reserved passage names.
Start
The first passage.
StoryTitle
The title of the story.
StorySubtitle
The subtitle of the story.
StoryAuthor
The author of the story.
StoryMenu
In Twine 1.4.2, the StoryMenu passage coresponds to the menu that hovers in the upper-right corner of the page in the Jonah story format, or on the left side of the page in the Sugarcane story format.
StorySettings
Used to specify certain options and settings.
Twine 1.4.2 Settings:
Undo: enables the player to "undo moves." In Sugarcane, this means being able to use the Back button in the browser. In Jonah, this means being able to use the “Rewind to here” link, and being able to click links in previous passages.
Bookmark: enables the player to use the “Bookmark” link in Sugarcane and Jonah. On by default.
Hash updates: this causes the current passage's bookmark URL to be automatically placed in the player's browser address bar whenever they change passages. This is off by default because the URLs can become very long and ugly quickly.
Prompt before closing: If the player tries to reload or close the page, the browser will prompt for confirmation. This is useful for long games - it would be unfortunate if the player lost a lot of progress due to an idle key-press.
Don't use default CSS: This removes most of the CSS used by the story format, allowing CSS programmers to write their own stylesheet redesigns more easily. Off by default - but including the text “blank stylesheet” in a stylesheet will set it on automatically.
ROT13: obfuscates the story's HTML source to dissuade people from spoiling themselves by reading it. Off by default.
jQuery: include the library or not
Modernizr: include the the library or not
StoryIncludes
Includes, "imports", other local or remote files during the HTML compilation process. In Twine 1.4.2, both Twine Story (.tws) and Twine Source (.twee) files can be used.
UserStylesheet
Although not an official keyword in most compilers, stories converted into Twee, or those without an existing passage tagged with "stylesheet", will sometimes be given a passage with the name "UserStylesheet". In most cases, this will also have the tag "stylesheet".
In Twine 2, this passage is the equivalent of Story Stylesheet.
UserScript
Although not an official keyword in most compilers, stories converted into Twee, or those without an existing passage tagged with "script", will sometimes be given a passage with the name "UserScript". In most cases, this will also have the tag "script".
In Twine 2, this passage is the equivalent of Story JavaScript.
Special Tag Names
Most Twee compilers understand two common tag names, stylesheet and script. These are usually loaded and run from passages tagged with them in alphabetical order.
Stylesheet
Any additional or overriding CSS rules for the story.
Script:
Any additional or overriding JavaScript code for the story.
The text was updated successfully, but these errors were encountered: