textallion, a simple word processor
Eric Forgeot
%%date(%Y-%m-%d)


% Tiny almost-Kiss Word Processor
% http://textallion.googlecode.com

%% DEF DOCUMENT METADATA. Use your own. Remplace the second part only, don't modify the xx DOCUMENT ## xx 
%!postproc(tex): 'xx DOCUMENT TITLE xx' 'Textallion - documentation'
%!postproc(tex): 'xx DOCUMENT AUTHOR xx' 'Eric Forgeot'
%!postproc(tex): 'xx DOCUMENT TAGS xx' 'documentation, manual, manuel'


%% DEF PERSONNAL STYLE (it should have a name such as sample.sty and or sample.css in your folder) 
%!style(tex): ../includes/sample
%!style(xhtml): ../includes/sample.css 

%% DEF PERSONNAL CLASS
%%!postproc(tex): '\\documentclass{article}' '\\documentclass{myclass}'

%% DEF TEXTALLION 
%!includeconf: ../core/textallion.t2t
%!postproc(tex): 'TEXTALLIONPATH' '../'

%% Alternative definitions path for TEXTALLION (not enabled)
%--!includeconf: /usr/share/textallion/textallion.t2t
%--!postproc(tex): 'TEXTALLIONPATH' '/usr/share/textallion/'


%% DEF additionnal macros (can be removed)

%!includeconf: documentation_symbols_inc.t2t 

%!--preproc(tex): "$" '{//..}'
%(this one is not activated. It's supposed to replace single line break by a real line break, which is not activated by default in txt2tags)

%!--preproc(tex): "==" '++'

%for adding IPA fonts (fontenc is included within tipa)
%!postproc(tex): '\{fontenc\}' '{tipa}' 

%!postproc(tex): 'IPATEXTALLION' '\\textipa{tEkstalj\~O}'
%!postproc(xhtml): 'IPATEXTALLION' 'tɛkstaljɔ̃'


%% adding an "alt" attribute to images with the syntax [image.jpg]{alt:your alternative text}
%!postproc(xhtml): '<img ([^ ].*?) alt=\"\"\/>( *)\{alt:([^ ].*?)\}' '<img \1 alt="\3" title="\3"/>'
%!postproc(xhtml): '<img ([^ ].*?) alt=\"\" ([^ ].*?)\/>( *)\{alt:([^ ].*?)\}' '<img \1 alt="\4" title="\4" \2/>'

% ( *) = zero or more whitespace


@@renewcommand@@sfdefault((phv))**

%%%% Beginning of YOUR document %%%%

= Manual =

%{ -- }
%@@begin((textsf)) @@small ((**
[../images/logo_textallion.png]{~~~~}
**TEXTALLION** ''[''IPATEXTALLION'']'' 
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 http://www.txt2tags.org]**.  {//..} {//..} 
__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{//..}
%@@hspace((0mm)) )) @@end((textsf))**
%{/-- }

== 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 http://txt2tags.org/].

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 documentation_en.pdf]), web page (this current page, or [this one using the slidy presentation format documentation_en_slide.html]), or ebook ([epub example documentation_en.epub]), from an __unique source__ ([source for all the previous documents documentation_en.t2t]).

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 http://anamnese.online.fr/site2/textallion/textallion.zip].

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


== Prerequisite ==

TeXtallion has been tested on those operating system:


=== Linux ===

[LaTeX http://www.latex-project.org/]  and [python 2 http://www.python.org] must be installed on your computer. Most distributions, if not all, have this by default.

For example Archlinux, Mandriva and Debian have [TeXlive http://www.tug.org/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 http://www.python.org] must be installed on your computer. Choose version 2 (for example python 2.7) because the version 3 is not compatible. 

- unzip the textallion archive for example into C:\temp\textallion (you can select another folder, but we assumed in the next examples textallion was installed into this one)

- Use LaTeX with [MiKTeX http://miktex.org/] for the creation of the pdf files: Choose the "basic" version of MiKTeX, if some files are missing during the first use of textallion, it will download them automatically ("install missing packages on the fly"). 

You can use [make http://gnuwin32.sourceforge.net/packages/make.htm] and some postscript manipulation tools (pstopdf, psutils (pdfnup, psbook), pdfjam etc). Get the "Setup program" and install it. Add C:\Program Files\GnuWin32\bin as a PATH variable into windows (system properties > environnement variables). 

For creating epubs, you can install [Calibre http://calibre-ebook.com/download_windows]


=== *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 http://www.macports.org/] systems.


== Use ==

%You can use 'make' in addition (optional makefile), and postscript tools as well (pstopdf, psutils (pdfnup, psbook), pdfjam etc)


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:

- **``make html``** to generate a html page.
- ``make slidy`` to generate a html presentation page.
- **``make pdf``** to generate a LaTeX document and then a pdf file. If the compilation goes well, there won't be any error written, and it should end with "entering extended mode".
- ``make pdfsmall`` for making a document with 2 pages in one (needs pdfjam, and the links won't be activated anymore: good for printing only)
- ``make booklet`` for making a recto-verso leaflet (needs psutils, links won't be activated anymore). The colums are not well aligned at the moment.
- **``make epub``** pour creating an epub file (electronic e-book), needs the free software [calibre http://calibre.kovidgoyal.net/] to make the conversion from the html file. You can also use [Sigil http://code.google.com/p/sigil/] in addition for reformatting your document.
- ``make clean`` to clean the folder from temporary files.
- ``make cleanall`` to clean the folder from temporary files, and erase every generated .tex and .pdf (needs a confirmation for security)
 - ``make configuration-update``, to compare with a diff tool (such as meld), the configuration files of the project for the makefile, css & sty from the latest installed version of textallion, and help update them if necessary.
 - ``make website`` to create an index page for setting online your html, pdf and epub files, with a qr-code for scanning with a phone.
- ``make all`` for making html, pdf, and cleaning temporary files.

You can also type ``export TEXTALLIONDOC=your_document_name && make pdf`` (without the .t2t at the end of your_document_name) and it will use the environment variable so you won't have to modify the makefile.

The sample.css file is an example of html style for your documents. It is also used in the creation of the epub document, if necessary.

Under windows, you can use the ``textallion.bat`` file. You may need to modify the paths in this script. We assumed textallion would be into C:\temp\textallion\

Check thoses paths are correct:

 - C:\Python26\python.exe
 - C:\Program Files\MiKTeX 2.9\
 - C:\Program Files\Calibre2



== Syntax ==

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

=== Txt2tags Markup ===

A short reminder of the syntax:

- ""**bold**""       :  **bold**
- ""//italic//""   :  //italic//
- ""__underline__"" :  __underline__
- SYMBtiretSYMBtiretstrikeSYMBtiretSYMBtiret      :  --strike--
- ""= title ="" (different levels)
- ""- list""
- ""+ numbered list""
- ""``code``""
- ``[image.jpg]``
- ``[link to a website http://www.homepage.com]`` : [link to a website http://www.homepage.com]
- ""| table |""


=== Additions ===

==== Extra symbols ====

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

- An initial is made with the symbol ``SYMBlettrine`` before the first letter of the word.
- A small space between 2 sections  is made with ``SYMBbigskip`` or ``SYMB2bigskip``
- A bigger paragraph is made with ``SYMBaldinea`` (add a little leaf @@ding((166))**)
- Another version with ``SYMBaldineb`` : @@ding((167))**
- The end of a section with 3 stars is made with ``SYMBtroisetoiles``
- You can also have those symbols (centered and on a new line) :

|| Description | symbol | code |
| moon first quarter | @@rightmoon** | ``SYMBlunep`` | 
| full moon  | @@fullmoon**  | ``SYMBlunef`` |
| moon last quarter | @@leftmoon**  | ``SYMBluned`` |
| sun  | @@sun** | ``SYMBsoleil`` |

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 ``SYMBpercentSYMBpercentindex`` where you want to place this index.

Index entries are made with ``SYMBindex`` (or ``SYMBindex2``) surrounding the word to be indexed. To use an alternative name for the indexed word, you can write for example ``SYMBindexapple{SYMBcaretfruit}``.


=== 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 | www.txt2tags.org]]



==== Linebreaks and non-breaking space ====

- Txt2tags by default won't break a line unless you have 2 blank lines in between.

If you prefer you can also add a space at the beginning of a line you want to break (specific syntax to textallion).

You can also force a line break with ``SYMBlinebreak``, or the simplified version ``SYMBlinebreak2``. 

If you want to copy and paste texts from internet or an other source, you may find tiresome to include the special line break marks (``SYMBbigskip``), so you can enable in the header of your document this command:

``` SYMBpostproc "SYMBdollar" 'SYMBlinebreak'
 
But it can lead to other annoyance, so use it with care.

For poetry or prosa, with several ligne break, the best is to start a line with a single space, so it will mean there will be a line break. In the case there is more than a single space, it will add an intentation to the line break.


- If you wish to add a non-breaking space in your text, you can use the ``SYMBnbsp`` symbol.


*-*-

==== Page Break ====

You can get a page break with ``SYMBpagebreak``.

*-*-


==== 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 ``SYMBfootnote2``.

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 footnoteSYMBfootnoteThis is the note.(1)SYMBfootnote.
```

will turn into:

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




*-*-


==== Image size ====


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

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

[../images/logo_textallion.png][10] (10)

[../images/logo_textallion.png][20] (20)

[../images/logo_textallion.png][30] (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.SYMBoggSYMB], which will add a HTML5 player in the browser. Only the free and open format [ogg/vorbis http://en.wikipedia.org/wiki/Vorbis] is supported, because contrary to [mp3 http://en.wikipedia.org/wiki/MP3#Licensing_and_patent_issues], it is directly compatible in most browsers: [Firefox, Chrome, Opera http://en.wikipedia.org/wiki/Use_of_Ogg_formats_in_HTML5].

Music example:

[../images/tbd_musique01.ogg]


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

Video example: (downloaded from an external website):

[http://upload.wikimedia.org/wikipedia/commons/7/79/Big_Buck_Bunny_small.ogv]


*-*-


==== Text size ====


- You can { ++ } increase {/++ } the text size by begining a part with ``SYMBsizeincBegin`` and ending it with ``SYMBsizeincEnd``.

- You can { -- } decrease {/-- } the text size by begining a part with ``SYMBsizedecBegin`` and ending it with ``SYMBsizedecEnd``.

*-*-


==== 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 ``SYMBitalicBegin`` et de le terminer avec ``SYMBitalicEnd``. 

De même pour des passages en gras, qu'il vous suffit de débuter avec ``SYMBboldBegin`` et de clore avec ``SYMBboldEnd``.

*-*-


==== Colors ====

You can use colors to a part of a text or a word, by using ``SYMBColorname of the colorSYMBDoubleArobaseText to colorizeSYMBSlashColor``. 

The basic colors are :

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

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


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


You can also specify the color with html code instead of the name, such as  #6D7D2E, which will display: @@COLOR@@#6D7D2E@@Here is my nice text in green@@/COLOR@@. 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 SYMBcenterBegin and SYMBcenterEnd:

{->--}
 A nice haiku
 Well centered poetic text
 It is what we're looking for
{-<--}

or with SYMBcenterBegin2 et SYMBcenterEnd2

@@begin((center))**
 A nice haiku
 A complicated method
 It's only for TeX lovers
@@end((center))**


*-*-

==== Columns ====


{|2|}

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.

{|0|}


=== 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 SYMBdoublearobase and the { et } by SYMBdoubleparenthopen and SYMBdoubleparenthclose. 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) :

@@begin((displaymath))**
@@frac((a))((b)) + @@sqrt[n]((abcd))**
@@end((displaymath))**

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@@footnote((Test of footnot))** (version with replacing code)

Beware, this way footnotes won't appear in the html version@@footnote((This note will be lost in html.))**

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.

 - **``make cyoa-html``** : create HTML file to publish the game on internet 
 - **``make cyoa-pdf``** : create the PDF file for printing the gamebook
 - **``make cyoa-epub``** : create the EPUB file to be displayed in a ebook reader or on a phone (android, iphone, ipad)
 - ``make cyoa-ramus``: Use [Ramus http://felix.plesoianu.ro//index.php/page:Software:Ramus] as an alternative HTML rendering. The output game will get _ramus.html at the end.
 - ``make cyoa-graph`` : create organigram
 - ``make cyoa-play`` : start the default browser and play the HTML file
 - ``make cyoa-hyena`` : convert your game to the [Hyena http://www.projectaon.org/staff/jens/], format, under the name your_game_export.gamebook
 - ``make cyoa-renpy`` : convert your game to the popular [Renpy http://renpy.org/] format, into a new folder your_game_renpy. Beware, this command will delete and recreate a previous folder with this name, so if you intend to modify the renpy code, move this folder elsewhere.
  - ``make cyoa-inform7`` : convert your game into [Inform 7 http://inform7.com] source code, with an  .i7 extension.
 

note: in the case cyoa-graph is not working on windows, you can render the generated cyoa-game_graph.txt with online tools such as http://ashitani.jp/gv/


=== 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:

- [Renpy http://www.renpy.org] is a popular format for creating visual novels. 
The export from textallion will recreate your paragraphs and your choices in the format used by renpy, generating a working folder containing everything you need to read later from renpy. You should then move that folder into renpy's workspace default to work further on this project (including addition of multimedia documents, images, sounds ...). Please note that the command ``make cyoa-renpy`` will completely destroy the original folder and replace it with a new one. So if you intend to add new elements in the code, you can either change the makefile accordingly, or move the folder elsewhere as indicated above.

To mean the end of a game, any occurrence of "THE END" will move the player to the end of the file, stopping the game.
The inclusion of images will be converted to the renpy format, and on each page, the background image will overlap the images already posted. To hide the images properly, although this is not an obligation, it is advisable to add ``$ hidemypic ("my_image.jpg")`` at the end of the paragraph after the use of a given image.

- [Ramus http://felix.plesoianu.ro//index.php/page:Software:Ramus] CYOA system, with a look similar to Undum, yet simpler to use.

- [Hyena http://www.projectaon.org/staff/jens/] is the format used by the Project Aon (Lone Wolf free version). There is also an implementation to replay those games, with [gamebook-engine http://www.freegameengines.org/gamebook-engine/]

- [Inform 7 http://inform7.com] is an interactive fiction system. It can create CYOA using the extension [Adventure Book by Edward Griffiths http://inform7.com/extensions/Edward%20Griffiths/Adventure%20Book/index.html]. You must have installed it prior to use it. 

The output file will be yourgame.i7. Then convert it to zcode (.z5) using Inform7. 

You may have to tweak a bit the source before being able to compile it in Inform, for example remove the "Page0" lines. Texts such as "So it will lead you to the 14" will be converted to "So it will lead you to the ''****''" (four stars), you'll probably want to edit this as well (you can just replace it to ''...'').


- [Twee (code) http://gimcrackd.com/etc/src/] is a format gamebook usable on the Internet, based on TiddlyWiki. `` make cyoa-twee`` will export to this format, unfortunately the version on the official site seems buggy, so no game can be generated (including examples in their archive)


*-*-

= Sample texts =[samples]

//see [examples.html 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 =

- [Quick reference guide quickref.pdf] in pdf (or in [html quickref.html]).
- http://lab.arc90.com/experiments/readability/
- http://www.epubread.com/ : firefox extension for reading epub
- http://www.fbreader.org/ : epub reader
%- http://www.framasoft.net/article2225.html : Règles typographiques 
- Some good text editors which support txt2tags syntax:
 - http://kate-editor.org/ 
 - http://www.geany.org/ 
 - http://www.scintilla.org/SciTE.html 
 - http://projects.gnome.org/gedit/



%!include: license.t2t


%!include: changelog.t2t


%!include: todo.t2t


%%index