Suggestions on howto package macros for sharing

Suggestions on HOWTO Package Macros for Sharing

This proposal is to establish suggested methods for sharing macro code so that it can be easily reused and modified. Please add to to document as experience refines our understanding of what works and what does not.

Please understand that we appreciate the work of all author/coders. There is no requirement to submit code using the formats below; these are merely suggestions that might make your code more likely to be shared, reused and improved by others.

The file

File format

Twee (.twee, .tw, .txt) files are preferred over Twine (.tws) files. The most common reason is .twee is a text file format. Text files can be viewed online, easier for version control software, and can be modified without the Twine authoring environment. You can read more about the Twee File Format

File naming

TwineQuest files

TwineQuest plugins should begin with tq. and end with a .twee extension. The rest of the filename is up to the author, but will normally have an author/org/collection part and the name for the plugin.
e.g. "tq.eturnerx.mobnamer.twee" is the filename for the TwineQuest plugin by eturnerx and the plugin is called mobnamer
e.g. "tq.d20.mob.twee" might be the filename for plugins that give D20 System capabilities to characters.

Core TwineQuest files will begin with TwineQuest.*.twee with the * being the actual core item. Typically author/coders will be creating plugins to TwineQuest since additions to core objects should be slow and deliberate. The expected lifecycle is that features will be proposed as plugins then migrate towards the core if they have near universal usefulness.

Other Twine files (Macros, stylesheets, mods to core)

Begins these filenames with a four digit number greater than 9000, a space, the word "macro", "extension" or "style" where that makes sense, another space then the name of the item. The filename uses the .twee
e.g. "9999 Macro br.twee"
e.g. "9991 Style GreenScreen.twee"
e.g. "9999 Macro back supporting labels.twee"

The numbering means that shared content will appear grouped in an alphabetical file listing. This means that complex Twine gamestories that spans multiple files will have some separation from the shared files. Using a four digit number higher than 9000 allows Twine authors to use other four digit number schemes in their own gamestories. The recommended numbers are:

• 9990 Extensions that modify the Twine engine (not the macros). These are custom display routines, customised history functions etc.
• 9991 Used for custom stylesheets that colour/theme a storyformat in some way
• 9999 For custom macros; whether these improve / modify an existing macro or are completely different.

Twee file layout

The first passage in a .twee file (TwineQuest or other) is a private passage that contains information about the .twee file. Because the first passage is private it is not output into generated .html story files. The passage title is the filename, a space and then the word "About". The passage tag is Twine.private. This passage is free format but it is suggested to be in Attribute-Colon-Newline format and contain information about license, usage, acknowledgements, version, contributors and/or examples.

::9999 Macro Example.twee About [Twine.private]
LICENSE: Public Domain
PURPOSE: 
A macro that serves as an excellent example of how
to be excellent in all that you code.

Well, it tries. And that's excellent.

USAGE:
<<example>>

CONTRIBUTORS: 
People
And even more people

This first passage can then be followed by as many other passages as necessary. If there is only a single passage (say for a macro) then it is suggested to title the passage using the filename without the word "About":

::9999 Macro br.twee [script]
try { macros['br'] = {
   // ... insert code here
}; } catch(e) { throwError(place,"Macro Example Error: "+e.message); }

This passage naming convention is to avoid passage title clashes and to make things a bit easier when debugging large gamestories.

Licenses

Please give the most liberal license that your conscience will allow. Ideally work will be public domain (no restrictions at all) but there is no requirement that this be so. Some author/coders would prefer a creative commons license which generally encourage attribution. Even with public domain licenses it is considered polite to attribute and acknowledge contributors and other authors.

The shared repository will probably accept a wide variety of licences for code that can be freely shared. This might even include code with restrictions on modification.