textallion, a simple word processor


Eric Forgeot

2011-07-24

Manual

TEXTALLION [tɛkstaljɔ̃] n.m. — (2009 ; from text, and unknown suffix -llion, probabl. animal origin or meaning the 1st. pers. plural. We can write textallion or TeXtallion.)

Word processor system using a wiki markup, for an attractive output, in PDF, HTML or EPUB, and using a simple keyboard-only format, instead of clicking on tools. Additionnaly, the document source can be read without a specific application. See txt2tags.

Citation:

« I send you a .t2t file as attachment, never tell me again you don't own the right piece of software to open it! »
William Grumbold, librarian

Presentation

The textallion project was made because of our consideration for the good and appealing quality of the LaTeX output, and also because of our love for the simplicity of txt2tags.

But there is also much frustration with LaTeX, it's perfect for writing scientific and complex books, but there is not way to quickly start writing prosa with it, without enduring the intrusive and complex syntax.

The goal of textallion is to use txt2tags as a preprocesseur, and keep its non-distracting formating marks, while being able to export easily into LaTeX, html and ePub. Txt2tags can already export to LaTeX, but there is little control on the output.

So with it you can publish on paper (pdf example), web page (this current page, or this one using the slidy presentation format), or ebook (epub example), from an unique source (source for all the previous documents).

By default, textallion will have all that is needed for writing a simple and nice looking book or roman:

Bold, italic, underligned, striked letters, colored text, page numbering, top header with title and separating line, bullet lists and numbered lists, image includes, support for footnotes, table of content.

Note: This project was first named "txt2tex". And sorry for the quick and dirty translation of the French manual

Getting TeXtallion

Latest version can be found there: http://code.google.com/p/textallion/downloads/list

There is also a mirror located there.

Older versions can be retrieved from http://anamnese.online.fr/site2/textallion/

Prerequisite

TeXtallion has been tested on those operating system:

Linux

LaTeX and python 2 must be installed on your computer. Most distributions, if not all, have this by default.

For example Archlinux, Mandriva and Debian have TeXlive

You can use the textallion_install.sh script (from a root shell), for copying everything needed into /usr/share/textallion/, or your folder of choice.

Windows

Python must be installed on your computer. Choose version 2 (for example python 2.7) because the version 3 is not compatible.

*BSD

Same as Linux, except you have to type gmake instead of make because the makefile is using GNU make. Texlive is not officially supported by FreeBSD, please use teTeX instead.

Mac OS X

Not tested yet. You should be able to use the BSD instructions and the macports systems.

Use

The two files textallion.t2t and textallion.sty are the definition and the style of the system. Normally, you shouldn't have to modify those files. For getting started with a new document, just make a copy of the sample.sty under a new name (your personnal style for your document), and copy the header of the sample_en.t2t, also under a new name, if possible the same as your new style, until the mark %%%% Beginning of YOUR document %%%% in the source. You can also use the textallion.sh script to initiate a new document.

Then, you just have to write your document and modify the basic appearance in the style file (margins, header, etc.). You can easily alter the size of paper, the size and name of the font, the size of the displayed text (implicitly defining the margins then). The syntax, which is quite easy to use, is described later.

In order to compile your html or pdf document, on an unix system, open a terminal in the folder of your document, modify in the makefile the line with DOCUMENT = sample_en to suit your own document name and type either:

Syntax

The general systax is the one of txt2tags, and we added our own.

Txt2tags Markup

A short reminder of the syntax:

Additions

Extra symbols

We added those symbols. They are made with 4 signs between braces (curly brackets):

Description symbol code
moon first quarter
☽
{ )) }
full moon
○
{ () }
moon last quarter
☾
{ (( }
sun
☼
{(  )}

You may also enter those symbols directly into the source if you wish, but they might be tiny to read in some plain text editors. You can't enter new unicode symbols if you want to publish to pdf (unless you adjust the preprocessor in your document, remember, almost everything is possible when using txt2tags ;) ) because this latex version doesn't use unicode, but the html output can handle this.

Some epub reader can't read those symbols, so they were replaced by stars * during the epub export.

For getting a m-dash (French conversation for examples), you can type three -, or even type a real m-dash —.

Table of Content and Index

TOC is generated automatically by txt2tags. Use the %%toc command anywhere in your document to place it. Otherwise, by default, it will be at the beginning.

Use of the Index is optional. To activate it, uncomment the \usepackage{makeidx} and \makeindex into your .sty file. Use the command %%index where you want to place this index.

Index entries are made with {^} (or { ^^ }) surrounding the word to be indexed. To use an alternative name for the indexed word, you can write for example {^}apple{^fruit}.

Links

As an alternative, if you prefer to write [description URL] for your links, it will be converted by textallion into the txt2tags syntax: [description URL].

Homepage of txt2tags

Linebreaks and non-breaking space

Page Break

You can get a page break with {/...}.

Footnotes

Footnotes are possible if you wrap those notes with °° (see example below and the source code of this document for further examples). You can access this symbol on qwerty keyboards with alt gr + 0 on Linux and alt+248 on windows.

For keeping the logical markup of textallion, it's possible to create footnotes with this symbol { °° }.

The LaTeX version will use numbered footnotes, while the html version will use a star (*) to make the footnote.

It's also possible to add between brakets a number for the html export, like this: 

  This is a text with an associated footnote°°This is the note.(1)°°.

will turn into:

This is a text with an associated footnote1 (This is the note.).

Image size

You can specify the images size, between brackets, the size in millimeters:

for example: [path_to/my_image.png][24]

(10)

(20)

(30)

In the html version, it will display it as a % of the page (I couldn't do better at the moment).

Adding sounds and musics

Especially useful for the CYOA module (see below), it's possible to add music with this syntax: [musique.ogg], which will add a HTML5 player in the browser. Only the free and open format ogg/vorbis is supported, because contrary to mp3, it is directly compatible in most browsers: Firefox, Chrome, Opera.

Music example:

You can do the same for ogg/theora videos, using the .ogv extension instead: [video.ogv]

Video example: (downloaded from an external website):

Text size

Italic or bold area

TODO Txt2tags cannot use italic or bold for several paragraphs. Si vous souhaitez mettre en italique un passage contenant plusieurs paragraphes, il vous suffit de le débuter avec { // } et de le terminer avec {/// }.

De même pour des passages en gras, qu'il vous suffit de débuter avec { ** } et de clore avec {/** }.

Colors

You can use colors to a part of a text or a word, by using @@COLOR@@name of the color@@Text to colorize@@/COLOR@@.

The basic colors are :

black blue brown cyan darkgray gray green lightgray lime magenta olive orange pink purple red teal violet white yellow

You can also use those colors, which are compatible with LaTeX and HTML (svg colors) :

AliceBlue AntiqueWhite Aqua Aquamarine Azure Beige Bisque Black BlanchedAlmond Blue BlueViolet Brown BurlyWood CadetBlue Chartreuse Chocolate Coral CornflowerBlue Cornsilk Crimson Cyan DarkBlue DarkCyan DarkGoldenrod DarkGray DarkGreen DarkGrey DarkKhaki DarkMagenta DarkOliveGreen DarkOrange DarkOrchid DarkRed DarkSalmon DarkSeaGreen DarkSlateBlue DarkSlateGray DarkSlateGrey DarkTurquoise DarkViolet DeepPink DeepSkyBlue DimGray DimGrey DodgerBlue FireBrick FloralWhite ForestGreen Fuchsia Gainsboro GhostWhite Gold Goldenrod Gray Green GreenYellow Grey Honeydew HotPink IndianRed Indigo Ivory Khaki Lavender LavenderBlush LawnGreen LemonChiffon LightBlue LightCoral LightCyan LightGoldenrod LightGoldenrodYellow LightGray LightGreen LightGrey LightPink LightSalmon LightSeaGreen LightSkyBlue LightSlateBlue LightSlateGray LightSlateGrey LightSteelBlue LightYellow Lime LimeGreen Linen Magenta Maroon MediumAquamarine MediumBlue MediumOrchid MediumPurple MediumSeaGreen MediumSlateBlue MediumSpringGreen MediumTurquoise MediumVioletRed MidnightBlue MintCream MistyRose Moccasin NavajoWhite Navy NavyBlue OldLace Olive OliveDrab Orange OrangeRed Orchid PaleGoldenrod PaleGreen PaleTurquoise PaleVioletRed PapayaWhip PeachPuff Peru Pink Plum PowderBlue Purple Red RosyBrown RoyalBlue SaddleBrown Salmon SandyBrown SeaGreen Seashell Sienna Silver SkyBlue SlateBlue SlateGray SlateGrey Snow SpringGreen SteelBlue Tan Teal Thistle Tomato Turquoise Violet VioletRed Wheat White WhiteSmoke Yellow YellowGreen

You can also specify the color with html code instead of the name, such as #6D7D2E, which will display: Here is my nice text in green. LaTeX won't be able to display this color, it will be replaced by gray.

Centering text

You can center some text (LaTex only) with a leading |

centered text

or by surrounding a paragraph with {->--} and {-<--}:


A nice haiku
Well centered poetic text
It is what we're looking for

or with @@begin((center))** et @@end((center))**


A nice haiku
A complicated method
It's only for TeX lovers

Columns

You can use the {|n|} symbol for getting n columns in your text, n being a value between 0 and 4. You can close the area with the same syntax but with n=0 or n=1.

LaTeX equations

Use { $$ } (both side). PDF export only. For html, you can copy and paste them in http://www.codecogs.com/latex/eqneditor.php

inline : \delta = 3 \times \sum X_i^2, ainsi que 4 - \sqrt X

offline : \delta = 3 \times \sum X_i^2

LaTeX code

Even if you're not supposed to, you can add specific LaTeX code by replacing the \ by @@ and the { et } by (( and )). If you wish the command to disappear from the html output, you have to end your command with 2 stars ** to indicate the end of the code.

You can also, more easily, surround your LaTeX code with the txt2tags syntax for verbatim (three ```) or the new tagged format (three '''), but it will include the LaTeX code into the html document, which might not be desired.

The source code of this document will gave you more example on how to add more latex options in your text. For example this mathematic formula (which won't appear in the html version) :

The verbatim version: 

  \begin{displaymath}
  \frac{a}{b} + \sqrt[n]{abcd}
  \end{displaymath}

A simple box:

@@Ovalbox((Example of text in the box))

This last example will appear odd (on purpose) in the html version because there is no ** at the end of this special command.

❦
Footnote examples:

We can include footnotes this way (version with replacing code)

Beware, this way footnotes won't appear in the html version

It's better to use this simpler form for keeping notes in the html version* (This note will be kept in the html version of the document)

CYOA module

With textallion, you can also create traditional "Choose Your Own Adventure" books, with the help of a "txt2CYOA" module.

Chapters

Your sections (chapters) will be created using the default txt2tags heading (level 2): 

  == z ==

Important: You must add spaces around the number to create the anchor.

Choices

To create a choice, use either : 

  - Description of the choice : z
  - Description of the choice : [z #z]. More words afterwards.

with z being replaced by the number of your section. Textallion will be able to detect that it's a choice, and link to the related heading.

You must use the syntax [z #z] if the number is followed by something and not alone at the end of the line.

Alternative for choices

It's not really advices to use this because it may clash with some other options (graphs, ramus for example).

You can add more descriptive links with : 

  ==17==[name_of_link]

and the call to this chapter would be : 

  - Go to this chapter : [17 #name_of_link]

Important: There musn't be space around the number in the heading!

You can also name your link, and redirect to a chapter: 

  - Enter [into the house 17]

it will remove the number from the displayed text, but the HTML link will still get the number so your player will be aware of it. The PDF version hyperlink will be broken (at the moment). Probably only useful for the EPUB version.

Pictures

You can add pictures with [yourpicture.jpg] (or .png)

To use wrapped pictures, type: 

  [yourpicture.jpg](~~~~)

(default textallion behavior)

Graph

It's possible to get a graph with all the chapters connected together.

You need to have graphviz installed to do that, and make sure each choice starts on one individual line, with a - and ends with the number of the choice.

You can invoque "make cyoa-graph" to produce the svg and png version.

Export to other game formats

By choosing to create games with textallion, in addition to the PDF, HTML and EPUB exports, you can also create games in those formats:

Sample texts

see examples.html for a few texts examples.

Example unix code

If you need to include some letters already found in the txt2tags code (such as the pipe |), you can prevent their execution by surrounding them with double quote ("")

find . -print | cpio -o -H newc | gzip -9 > ../initrd.gz

Useful ressources

License and credits

All textallion codes and hacks are released under a BSD license 

  Copyright (c) 2008-2011, Eric Forgeot. 
  All rights reserved.
  
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are met:
      * Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
      * Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
      * Neither the name of the <organization> nor the
        names of its contributors may be used to endorse or promote products
        derived from this software without specific prior written permission.
  
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

All personal artworks and documentations, if applies, are licensed under the CC-BY-SA license.

You can contact me about Textallion:

Textallion is using txt2tags as a backend. Txt2tags is covered by the GNU GPL.

Credit is due to:

Changelog

The releases are in the form: textallion_year-month-day_artistname.zip. If some additions are made during the same month, there won't be any new release (artist code) name, but the new version will have the date updated, for example: textallion_2010-08-13_chasseriau.zip and then textallion_2010-08-15_chasseriau.zip

Todo and known bugs

Syntax, backend and docs

HTML

PDF (LaTeX and XeTeX)

EPUB

Windows

txt2cyoa