A lot of projects ported from the old metanohi site.

site/projects/movact/index.org

@@ -0,0 +1,577 @@
+#+title: movact
+#&summary
+A program that reads, runs and converts hypertext fiction files
+#&
+#+license: bysa, page
+#+license: gpl 3+, program
+#&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.
+
+[[movact-0.5.1.tar.gz][DOWNLOAD&large]] [[movact-0.5.tar.gz][{(or old version)}&small]].
+
+[[wah.mvct.html][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:
+
+#+BEGIN_SRC
+#!/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]...
+#+END_SRC
+
+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:
+
+#+BEGIN_SRC
+Document
+    |
+    ·-- META part
+    ·       |
+    ·       ·-- subpart
+    ·       |
+    ·       .-- .......
+    |
+    ·-- MAIN part
+            |
+            ·-- subpart
+            ·      |
+            ·      ·-- paragraph | reference
+            ·      |
+            ·      ·-- .....................
+            |  
+            ·-- .......
+#+END_SRC
+
+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:
+#+BEGIN_SRC
+·---------------------------------------------------------·
+|_ ...xxx    ~  xxx = name of part (either META or MAIN) _|
+|_ ..xxx     ~  xxx = name of subpart                    _|
+|  .xxx yyy  ~  xxx = reference to xxx, written as yyy    |
+·---------------------------------------------------------·
+#+END_SRC
+
+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:
+
+#+BEGIN_SRC
+..open button
+Åben
+#+END_SRC
+
+This 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:
+
+#+BEGIN_SRC
+..point
+(
+    ('A. ', ('A', 'a')),
+    ('B. ', ('B', 'b')),
+    ('C. ', ('C', 'c'))
+)
+
+..confirmed
+('y', 'yes')
+#+END_SRC
+
+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:
+
+#+BEGIN_SRC
+..start
+[TEXT]...
+#+END_SRC
+
+As long as this is present, movact will run. To extend your movact story, you
+add references:
+
+#+BEGIN_SRC
+..subpart
+Some text..
+You have a choice:
+.subpart2 Go here!
+#+END_SRC
+
+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:
+
+#+BEGIN_SRC
+..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!
+#+END_SRC
+
+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:
+
+#+BEGIN_SRC
+..tree
+You are next to a tree\# and this is not a comment
+#+END_SRC
+
+..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:
+
+#+BEGIN_SRC
+..jupiter-arrival
+The armadillo breaths heavily. It notices a bunch of empty lines.
+.mars Escape!
+---
+#+END_SRC    
+
+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:
+
+#+BEGIN_SRC
+..123
+321
+
+\---
+#+END_SRC
+You could also just do this:
+
+#+BEGIN_SRC
+---
+---
+#+END_SRC
+
+*** ='[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:
+
+#+BEGIN_SRC
+...META
+..title
+ABC
+
+...MAIN
+..start
+BCA
+
+[end]
+..start
+Welcome to the alphabet story!
+#+END_SRC
+
+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
+[[mailto:ns@metanohi.org][ns@metanohi.org]].
+
+
+
+* 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
+