18 KiB
movact
#&summary A program that reads, runs and converts hypertext fiction files #&
#&toc
movact
#&img;url=art/movact-logo-256.png, center, alt=movact, width=256, height=256, medlink=art/movact-logo.svg
Info from the readme
#&pre
=======================================================================
movact: a program that reads, runs and converts hypertext fiction files
=======================================================================
#&
movact is a small suite of software that aims to aid in the development and use of hypertext fiction. With movact everyone is able to create hypertext fiction using a very simple syntax. It is hoped that the stories created for movact be distributed throughout the world (and ultimately the universe) for everyone to read and perhaps build upon, though no one is forcing anyone.
This is the combined README/manual.
Version
The current version of movact is 0.5.1. This version can be considered quite stable, although it is the second version to be released.
How to get movact
movact will always be online at http://metanohi.name/projects/movact/, where documentation will also be available.
DOWNLOAD&large {(or old version)}&small.
Try a live example, converted to HTML using a movact tool.
License information
I have chosen to make movact available under the GNU General Public License version 3 or (optionally) any later version.
#&pre movact 0.5.1 Copyright © 2009, 2010 Niels Serup License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html">http://gnu.org/licenses/gpl.html> movact is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. #&
This license applies to all files in the "movactorg/" directory, except for the files found in the "external/" subdirectory. Those files are released under GPL-compatible licenses.
movact also has art. It's located in the "art/" directory. All graphics are released under the Creative Commons Attribution/ShareAlike 3.0 Unported license ("CC BY-SA"). More specifically, the files licensed under CC BY-SA 3.0 are:
- art/movact-logo-256.png
- art/movact-logo-64.png
- art/movact-logo.svg
These three files are all copyright © 2009, 2010 Niels Serup
Dependencies
For movact to run, you must use at least Python 2.4 (though 2.3 may work with limited functionality). To run the GTK+ frontend, you should also have PyGTK 2.6 or newer installed.
Most modern GNU/Linux distributions have both Python and PyGTK in their repositories for easy downloading and installing. On DEB-based systems (like Debian, gNewSense, etc.) you can do this:
$ sudo apt-get install python python-gtk2
On RPM-based systems (like Fedora, CentOS, etc.) you can do this:
$ sudo yum install python pygtk2
Structure
movact is module-based. It consists of several parts.
Core
The core of movact takes care of the basic stuff, such as loading and parsing.
Frontends
The frontends are used to actually run movact files after they have been loaded and parsed in core. There are currently only two frontends in movact: a GUI frontend in GTK+ and a terminal frontend in.. well, text. Support for other frontends may come in future releases.
Converters
movact runs fine without the converters, but the converters do not run without the movact core. It is currently possible to convert movact data files to 4 formats: HTML (with one page for each movact part), HTML+JavaScript (with only one HTML file), XML and pure text.
Art
movact has its own mascot! Now, that's important! Graphics are used to spice things up a little. It is believed that the mascot is a mammal, but that's the only known fact about it.
Installation
movact currently does not support a true installation method. Instead, it relies on the script "fake-install.sh". You can use this script to link the different movact frontends, as well as the movact converter, to "usr/local/bin", which means that you can run movact just by typing "movact-gtk" or "movact-terminal" in a terminal and convert movact files just by typing "movact-convert" in a terminal. The script also asks you to choose a default movact frontend, which will be executed when "movact" is typed in a terminal.
Included stories
movact includes a small variety of stories: One "real" story consisting of several hundreds lines of human-readable text, plus a few mini stories that exist mainly for the purpose of testing the movact parser.
The "real" story is available under the CC BY-SA 3.0 Unported license.
movact in command
YOU have the freedom to decide what movact does and what it doesn't – though only to some extent. By default, movact tries to autoload progress when a user opens a story; this can be disabled. By default, movact autosaves progress whenever the user does something; this can be disabled as well. When using the terminal frontend, there are a couple of basic commands that are neccessary to know: #&pre
- /back : go one step back
- /reset : reset story and restart at the beginning
- /current: make movact display the current part name
- /open : open a new file
- /load : load a savefile
- /save : save progress
#& These commands can be modified by movact stories, so they are not necessarily always like this. When using the GTK+ frontend, just use the buttons.
movact saves to and loads from "$HOME/.movact/autosaves/" (e.g. "home/niels.movact/autosaves/").
Using the command line
There are several advantages of running movact in a terminal (or "console"):
- You will be able to see any eventual errors that may appear.
- You can pickle a story for quicker loading times.
- You can tell movact not to autosave or not to autoload.
Using a terminal will still allow you to use a graphical frontend.
If you plan to run movact in a terminal, remember to do this at some point:
$ movact --help
And, eventually, this:
$ movact-convert --help
These commands will display a short piece of text that will show you how to handle movact.
Syntax
A large part of movact is its syntax. A typical movact document looks like this:
#!/usr/bin/env movact
# Author and license
ZERO
...META
..title
A great story
..start
Welcome to the greatest story. You will experience experiences.
..end
That was that.
...MAIN
..start
You have no recollection of who you are or where you are.
In front of you stands a giant cat. What do you do?
.cat-run Run for your life
.10 Count to 10
.cat-talk Talk to the cat
..cat-run
[TEXT]...
..10 // 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
[TEXT]...
..cat-talk
[TEXT]...The basic syntax of movact should be possible to perceive looking at the example.. I guess. To get a better grasp of how the syntax is, it is a good idea to examine and modify the existing stories in the 'stories/' directory. Note that the first line in the example is used to more easily run movact on systems that support '#!' lines. On other systems it will just be ignored. When it works, however, it should be possible to simply type
$ ./a-story
..instead of
$ movact a-story
Parts
movact document consists of two parts: a META part and a MAIN part. Each part can be separated into subparts. META subparts cannot be separated further, but MAIN subparts can. In ascii art a movact document looks like this:
Document
|
·-- META part
· |
· ·-- subpart
· |
· .-- .......
|
·-- MAIN part
|
·-- subpart
· |
· ·-- paragraph | reference
· |
· ·-- .....................
|
·-- .......Even if your document layout/syntax seems to be ok, that does not have to be the case. When writing movact documents, one thing is absolutely necessary: the version. This isn't the version of the story you're writing (there's no way to specify that as a separate value) but the version of the parser that you're calling (a bit similar to "doctype" in HTML words). The version must always be the first real line in a story, i.e. it must be preceded only by comments and empty lines or lines with spaces only. Currently, the only supported version is "ZERO".
Overview:
·---------------------------------------------------------·
|_ ...xxx ~ xxx = name of part (either META or MAIN) _|
|_ ..xxx ~ xxx = name of subpart _|
| .xxx yyy ~ xxx = reference to xxx, written as yyy |
·---------------------------------------------------------·Except in the case of references, xxx can include spaces.
You can indent text any way you want to. When reading the name of a part or subpart, movact will trim it for spaces. Both '..start' and '..start ' count as 'start', whereas '..start x' counts as 'start x'.
META part
META subparts can be used to customize movact. A META subpart will always look something like this:
..open button
ÅbenThis will modify the text of the "open a file"-button in GUI frontends to "Åben". The default is "Open". It is not a need to actually specify a META part. If a META subpart is not specified, the value will default to.. a default value. Default values are always strings, except in the case of the 'point' subpart and the 'confirmed' subpart, in which lists are used.
To see the default values, look at 'movactorg/core/defaults.py'.
To modify 'point' and 'confirmed', write something like this in your META part:
..point
(
('A. ', ('A', 'a')),
('B. ', ('B', 'b')),
('C. ', ('C', 'c'))
)
..confirmed
('y', 'yes')This list syntax is borrowed from Python. If you want only one list item, do this:
('litem1', )
movact only uses the values defined in 'movactorg/core/defaults.py', but you can specify other meta data as well, though it has no use. In general, if you want to specify special information, do it using comments at the top or bottom of your file.
MAIN part
MAIN subparts are necessary. Stories consist of MAIN subparts. A story will need at least one MAIN subpart to actually function, though it will need many more to actually resemble a story. The one very important subpart must be named 'start'. So, all movact files must have lines like this in the MAIN part:
..start
[TEXT]...As long as this is present, movact will run. To extend your movact story, you add references:
..subpart
Some text..
You have a choice:
.subpart2 Go here!This will display the two first lines in the subpart as standard text, and the final line as a reference to another subpart named 'subpart2'. How references are shown differ in frontends. References can be anywhere in a subpart. They can be both before and after standard text. It is the period ('.') that tells movact that it's a reference. If a subpart has no references, movact ends the game.
Commenting and escaping
As movact documents can grow quite large, it is important to be able to comment one's story. There are three ways of using comments in movact:
/*...*///...#...
So, you can do something like this:
..tree
You approach the tree.# The human approaches the tree
The squirrel/* ..where did that come from ? */ helps you.
It seems nice.// Squirrel turns evil in ..forest!This will not print "# He approaches the tree", "* ..where did that come from ? *" and "/ Squirrel turns evil in ..forest!". Note that there are no limits as to how /*…* can be arranged. They can easily span several lines.
Now, allowing all these different types of comments has its disadvantages. Sometimes people may want to use the '#' character as a non-comment character. To do this, they must escape it using a backslash. So this:
..tree
You are next to a tree\# and this is not a comment..will print "You are next to a tree# and this is not a comment". Note that it doesn't print the backslash.
Of course comments are not the only textual things that you can escape. Apart from comments, you can escape periods (both '.', '..' and '…') as well as other things that haven't been explained yet. As a rule, whenever there's a special block of characters, you can escape it. This is generally true.
If you want to show a backslash before escapable places, you have to type two backslashes. In normal places just one backslash will do.
Special features
movact has several extra features for the advanced users.
'---'
First, '---'. The way movact splits subparts is by reading when the next line
that matches the regex '\.\..+' appears. All empty lines before that line are
removed from the previous entry. To avoid this, one can append '—' to the
very end of one's subpart. For example:
..jupiter-arrival
The armadillo breaths heavily. It notices a bunch of empty lines.
.mars Escape!
---Normally, the empty lines would not be printed, but because the '—' is there, they are. The '\n—' is not printed, however. To print '—' at the end, just write this:
..123
321
\---You could also just do this:
---
---
'[end]'
Normally you would just arrange your document like the ascii art diagram shows. You're not forced to do it that way, however. First of all, you can start with MAIN and end with META. But it's also possible to use MAIN and META interchangeably. This can be achieved by simply writing META, then MAIN, then META, etc. There is also another way, though. One can choose to use the '[end]' string, like this:
...META
..title
ABC
...MAIN
..start
BCA
[end]
..start
Welcome to the alphabet story!After '[end]', the movact parser goes back to META. One could have typed '…META' instead of '[end]' and achieved the exact same result. '[end]' can also be escaped.
'%$' and '$%'
Sometimes it can look nice with a string like this:
#################################################
But it would be annoying to type '\#\#\#' etc. This is why '%$' and '$%' exist. In any movact document, one can type '%$###########$%'. This will escape all the '#' and subsequently print all of them. It will not print '%$' and '$%'. As a matter of fact, '%$...$%' will escape everything escapable within the magic strings. These strings can also be escaped. To show a '%$', you'll have to either write '\%$' or '%$%$$%'. To show a '$%', just write '$%', as long as it isn't preceded by a '%$', in which case you'll have to write '\$%'.
Errors
The movact parser wants everything to be in perfect shape. Everything must be certain. This is why it's happy to print error messages; as a matter of fact, the movact parser was stderr in its former life.
…
The point is, if the syntax or the organization of the content is odd, movact will print an error. But it will only print one error. If you fix that error and then try running movact again, there's a risk that you may still get an error, though this time a different one. If you have produced a large story, it can be troublesome to fix errors one by one. To get a proper answer, the movact parser itself has agreed to be interviewed.
#&pre INTERVIEWER: So, movact parser, why do you show only ONE – as in the number 1 – error at a time? Is it not a bit odd? movact PARSER: No, I don't think so. In this world – no, in this universe – people are using their lifes on fixing errors. This is an unfortunte development, I think. INTERVIEWER: But, isn't fixing errors, bugs and the like a good thing? I mean, humans wrote programs and humans err, right? movact PARSER: Well, they do. But I'm not a human. I'm a piece of software. INTERVIEWER: You were written by a human. movact PARSER: … ERROR! ERROR! ERROR! CANNOT COMPREHEND. NOT A QUESTION. INTERVIEWER: OK, easy now. I kind of get the gist that you you want people to simply not make mistakes. Is this correct? movact PARSER: Yes. INTERVIEWER: I see. But what if humans choose to modify your code? Would that not mean that there is always a risk of having new bugs introduced to your system? movact PARSER: No. While people may freely modify my code, it is important to note that they are merely modifying copies of me. I am who I am, and that fact cannot be changed. I am bug-free. INTERVIEWER: I thank you for the interview. movact PARSER: … ERROR! ERROR! ERROR! CANNOT COMPREHEND. NOT A QUESTION. #&
The movact parser may have a few unknown quirks. It has ben fed with various different files, of which all seemed to work, but.. Please report any bugs to ns@metanohi.name.
Less than important notes
Not everything can be considered important.
Reason for choosing the name "movact"
It's a combination of the word "movie" and the word "act". Since the program is about reading fictional works, the name should also be fictional.
Command-line tweaks (for the sake of completeness)
If you are using movact from a terminal or console, you should note that "-h", "–help", "-v" and "–version" are special arguments, as they can be used only when no file is present. To use a file that has a name similar to one of these arguments, type its filename twice. This is not necessary if you are using one of the real arguments, such as '-d' or '–pickle', along with the filename. This means that trying to load a file with the name "-h" requires you to write "movact -h -h". If you need to load a normal movact file that ends on ".pickled", you have to escape it, or movact will try to unpickle it. To escape it, place a backslash in front of it, like this:
$ movact \not-a-pickled-file.pickled
If the name of your non-pickled file ends on ".pickled" but starts with a backslash, you have to do this:
$ movact \\not-a-pickled-file.pickled
etc.
When using movact-convert, note that case is ignored. "XML" and "xml" mean the same.
TODO
- Make a proper install script that also makes the program appear in the "Applications" menu on systems that support that
- Create a DEB package
- Improve the GTK frontend
- Add a curses frontend
- Add support for variables
- Create a man page, eventually using help2man
CHANGES
v0.5.1: Fix in the JavaScript/HTML converter; now works when cookies are disabled.
v0.5: FIRST RELEASE