metanohi/site/projects/movact/index.org

#+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