greyelf
commented
6 years ago re: the Special Tag Names. It may be a good idea to point out that they are case-sensitive and need to be all lower-case.
Closed videlais closed 5 years ago
greyelf
commented
6 years ago re: the Special Tag Names. It may be a good idea to point out that they are case-sensitive and need to be all lower-case.
tmedwards
commented
6 years ago 1) Notation. While it's legal to do so, I think we should generally consider it bad form to snuggle passage header components. For example:
/* VALID, BUT BAD */
::My Styles[stylesheet]
/* GOOD */
:: My Styles [stylesheet]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 ([, ]) within passage names and tags. This is also something we should nail down more firmly within the specification—though that's a separate concern.
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. StoryTitle and script vs. StoryTitle and Script—even in headings. I'd also suggest listing them in alphabetical order—e.g. script before stylesheet.
3) The Special Passage Names section lists UserScript and UserStylesheet. Neither are special passage names in any compiler and we should not list them as such. Even with the explanation that they're actually not, it could create confusion. The entries for the script and stylesheet special tags should be sufficient.
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:
These are usually loaded and run from passages tagged with them in alphabetical order.
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 script and stylesheet special tag entries do not mention their Twine 2 counterparts, Story JavaScript and Story Stylesheet. They are mentioned within the Special Passage Names section's UserScript and UserStylesheet entries, but as noted (in no. 3) those really should be removed.
videlais
commented
6 years ago Updated from @tmedwards's feedback. Now includes more details and examples from Tweego and Twee2 documentation.
The notation is written as a series of three parts for the header of each passage:
<123,456>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:
:: Snoopy [dog peanuts]
Snoopy is a dog in the comic Peanuts.
:: Charlie Brown [person peanuts]
Charlie Brown is a person in the comic Peanuts
Many compilers understand and process certain case-sensitive keywords differently. The following is a common set of reserved passage names.
StartThe first passage.
Example:
:: Start
A beginning!StoryTitleThe title of the story.
Example:
:: StoryTitle
A Named StoryStorySubtitleTwine 1.4.2:
The subtitle of the story.
Twee2:
Ignored during HTML compilation process.
Example:
:: ```StorySubtitle```
The subtitle of this storyStoryAuthorTwine 1.4.2:
The author of the story.
Twee2:
Ignored during HTML compilation process.
Example:
:: ```StoryAuthor```
John SmithStoryMenuTwine 1.4.2:
Corresponds 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.
Twee2:
Ignored during HTML compilation process.
Example:
:: StoryMenu
Content of the story menu!StorySettingsUsed to specify certain options and settings depending on the compiler used.
Twee2:
Ignored during HTML compilation process.
Optional Tweego Settings:
ifid: the story's IFID (Interactive Fiction IDentifier)Optional 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: 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.
exitprompt: 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.
blankcss: 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.
obfuscate: obfuscates the story's HTML source using ROT 13 to dissuade people from spoiling themselves by reading it. Off by default.
jquery: if the jQuery library should be included or not
modernizr: if the Modernizr should be included or not
Example:
:: StorySettings
undo:on
bookmark:on
hash:on
exitprompt:on
blankcss:on
obfuscate:rot13
jquery:on
modernizr:onStoryIncludesA list of any local or remote files to combine with the story during the HTML compilation process.
Tweego:
This passage is ignored, as Tweego will bundle any JavaScript source files automatically as it detects them.
Twee2:
Other Twee2 compiled files (.tw2) can be used.
Twine 1.4.2:
Both Twine Story (.tws) and Twine Source (.twee) files can be used.
Example:
:: StoryIncludes
localfile.tws::@includeTwee2:
Include the contents of another file at that point in the code. Does not work recursively.
Example:
::Garden [haml]
%p
The garden winds around decorative trees.
%p
::@include description-of-house.tw2Passage headers can contain any collection of tags. Two of the most common are stylesheet and script, but some Twee compilers such as Tweego and Twee2 also recognize and use others.
stylesheetAny additional or overriding CSS rules for the story.
Twine 2"
This is the equivalent of Story Stylesheet and is often translated as UserStylesheet[stylesheet].
Tweego:
Unnecessary. Tweego automatically incorporates all CSS (.css) files it finds.
Example:
:: UserStylesheet[stylesheet]scriptAny additional or overriding JavaScript code for the story.
Twine2:
This is the equivalent of Story JavaScript and is often translated as UserScript[script].
Tweego:
Unnecessary. Tweego automatically incorporates all JavaScript (.js) files it finds.
Example:
:: UserScript[script]scss stylesheetTwee2
Any additional or overriding CSS rules written in SASS.
Example:
::MyCoolStylesheet [scss stylesheet]
body {
background: #eee;
}
tw-passage {
tw-link {
color: red;
}
}coffee scriptTwee 2
Any additional or overriding CoffeeScript for the story.
Example:
::SomeAwesomeCode [coffee script]
alert 'This message will appear when the adventure starts!'hamlTwee 2
Any additional HAML code.
Example:
::NicksBar [haml]
%p
Nick's Bar is exactly the kind of nightspot that helps you remember why you quit drinking.
%p
%strong What would you like to do?
%ul
%li [Nick<-Talk to the bartender]
%li [BarToilet<-Go to the bathroom]twee2Twee 2
Additional configuration options or Ruby code to run during the HTML compilation process.
Example:
::Configuration [twee2]
Twee2::build_config.story_ifid = '41AB7776-D198-40F5-BD54-0493D49DA58C'
Twee2::build_config.story_format = 'Snowman'
mcdemarco
commented
5 years ago 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).
greyelf
commented
5 years ago the references to UserStylesheet and UserScript should be retained
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.
mcdemarco
commented
5 years ago the references to UserStylesheet and UserScript should be retained
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.