GaTeX: An ASCII Document Formatting System
Posted: Tue May 22, 2007 3:14 pm
BETA VERSION: Release Gamma (stable)
Download here (latest version): Format.ini with extra styles (wiwiland, filefront):
(fr) Voir aussi le sujet sur Wiwiland : http://forum.wiwiland.net/index.php?showtopic=39700
Download here (latest version): Format.ini with extra styles (wiwiland, filefront):
Code: Select all
{===============================================================}
{ GaTeX: An ASCII Document Formatting System }
{---------------------------------------------------------------}
{ Version: Gamma }
{ Author: Gamall Wednesday Ida }
{ Web: gamall-ida.com }
{===============================================================}
{===============================================================}
{ Introduction }
{===============================================================}
Oftentimes, one needs to write documents in raw text format. For
instance, documentation for mods or programs is best written in
plain text, since it is the only truly universal format. The
problem is, raw text documentation looks ugly, unless you spend
a ridiculous amount of time fine-tuning your ASCII layout.
This program proposes a way to typeset acceptable ASCII
documents almost as quickly and effortlessly as if you didn't
have to worry about the layout at all.
Please note that this program is still in Beta version, which
means it is absolutely not finalized yet. As it stands, it is
more of a proof of concept or a trailer ;-)
{===============================================================}
{ How does it work ? }
{===============================================================}
o==--~~ Structure of the files
o--------------------------------------------------o
The program depends on the file "format.ini", which contains the
formatting specifications for at least one style : the DEFAULT
style, with which the file you are presently reading has been
generated. Please open "format.ini" right now, and try to see
how it is structured... Let us consider the part "header_in",
which should look quite like that:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
{ header_in
$type = text
%width = 65
$align = CENTER
$left = "{ "
$right = " }"
$()in = \opacc\rep{=}\closeacc
$()out = \opacc\rep{-}\closeacc
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These lines describe the way text belonging to the first part of
the header, called "header_in", will be displayed. Now, open the
source text for this file, "Readme.gat", with your favourite raw
text editor. Look at the few first lines :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\header_in
GaTeX: An ASCII Document Formatting System
\end
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
And now, compare the data in both format.ini and Readme.gat to
the three very first lines of this file:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
{=============...=======}
{ GaTeX: ect... }
{-------------...-------}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note that the name "header_in" is specific to the style DEFAULT.
You can very well change it or / and define styles where the
logical parts have completely different names...
o==--~~ How do I get started ?
o--------------------------------------------------o
First, you have to make sure that a correct format.ini file is
in the same directory than GaTeX.exe. Then you can go ahead and
create a file for GaTeX. You can use any extension, but I
recommend '.gat', for obvious reasons. The gat file must contain
both a valid \style and a valid \output instructions.
A good starting point would be the demo file generated by GaTeX:
Just start GaTeX.exe without arguments, and enter a name for it.
This demo file is not much, but it is ready to compile...
It is also warmly recommended to mess around with Readme.gat,
the GaTeX source for the present file.
To compile a gat file, just drag and drop it onty GaTeX.exe's
icon. Or use the command line. The compiled file will be created
as a sibling of the gat file.
{===============================================================}
{ GaTeX syntax }
{===============================================================}
o==--~~ In format.ini
o--------------------------------------------------o
-> Execution parameters.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$version = "BETA"
%popup = 1
%terminate = 1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The version statement is important, since if it is not defined
(or void: ""), GaTeX will deem format.ini inappropriate and
refuse to work.
If 'popup' is not set to 0, the compiled plain text file will be
displayed as soon as created. It is very strongly recommended to
leave that at 1.
If 'terminate' is not set to 0, the program will terminate as
soon as its job is done, unless of course there are errors.
-> Creating and altering styles
I won't document the styling aspect of format.ini yet for the
following reasons:
1° The format used is utterly straightforward. I don't
think a documentation is really needed. Anyone messing with the
files for ten minutes should be ready to go.
2° As GaTeX is still in Beta stage, it may evolve. There is
little point in writing now a lengthy documentation which may
become partly obsolete shortly.
This being said, for the time being, in stead of an extensive
documentation, I offer support to whomever might need it to
create and debug their styles. See the section about support
below.
o==--~~ In the gat file
o--------------------------------------------------o
Note that unless explicitly stated otherwise, a 'command'
occupies a whole line. Commands always start with a '\'. As
mentioned before, the first two commands in a GaTeX input file
must be \style{YOUR_STYLE} and \output{PATH_TO_OUTPUT_FILE}.
After that, everything needs to be in a block, starting with
\BLOCKS_NAME and ending with \end. In the very special case of a
verbatim-type block, the \end command must have the escape
string of the verbatim block as an argument, else it will be
ignored. \end{verb}, for instance, if $escape = verb.
The 'line' command is an exception to this rule: it will create
a new line when used in a text-type block, but can also be used
on its own between blocks. It will also work used at the end of
a line of text, unlike most commands which need to have the
whole line for themselves.
In text blocks, the 'tab' command, which should be used very
sparingly, if at all, is replaced by the content of the $tab
variable in format.ini. Note that this is NOT a standard
tabulation. Those should never be used, since there are no two
software which display them the same way. Using the tab key
means broken layout. 'tab' can be used inline, of course.
The '-' command (pseudo-hyphen) can be used once in every work
of your text. It won't be displayed, but it just tells GaTeX
that the word can be cut there. For instance, you could write
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
His tactless floccinaucinihi\-lipilifications were... etc
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(Yes, this is a real word, by the way) and it will either be
displayed in full or cut in two. You cannot cut a word in more
than one place though.
o==--~~ In both
o--------------------------------------------------o
-> Special characters commands:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\\ stands for '\'
\opacc stands for '{'
\closeacc stands for '}'
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Those commands are necessary to allow use of the special
characters used to denote GaTeX commands: the commands in GaTeX
look very much like those in LaTeX: an expression such as
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\cmd{arg1}{arg2}...{argn}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
stands for a call of the function 'cmd', with arguments 'arg1'
to 'argn'. Note that such an expression will be parsed by GaTeX
everywhere but in a 'verbatim' block.
{===============================================================}
{ Miscellaneous }
{===============================================================}
o==--~~ Why such a strange name: 'GaTeX' ?
o--------------------------------------------------o
I am a fan of the LaTeX typesetting system. It is extremely
popular in the mathematical community, but unfortunately not
very well-known outside of it. It is most excellent for any
document with mathematical formulae in it, but it really is
suitable for pretty much anything. Except for making coffee,
perhaps. Give it a try if you get bored with Word and its awful
equation editor. It is free software, of course.
Anyway, I named my ASCII typesetting system 'GaTeX' as a bow and
pun directed towards TeX and LaTeX :-) GaTeX's syntax will also
look strangely familiar to weathered LaTeX users.
o==--~~ Are there any other plain text formatters ?
o--------------------------------------------------o
There is troff, groff, unroff and all that tribe... I am not
sure whether there are windows implementations. Probably. I
didn't look very hard. These have their roots in good old UNIX.
So, without having tried them, I feel quite safe making the
following assumptions:
1° They are powerful. Much more powerful than I need an
ASCII text processor to be.
2° The syntax will kill you...
If you have been using these, or any other formatter, I'd
welcome your opinion about them, whether they are easy to use or
not, which features they have (or not) that make them efficient
and 'cool' etc...
o==--~~ The 'File generated by...' notice
o--------------------------------------------------o
A kind of stamp is automatically generated by GaTeX at the end
of each compiled file, which looks more or less like that
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------+
| File generated with 'GaTeX',|
| an ASCII typesetting system |
| by Gamall Wednesday Ida. |
| http://gamall-ida.com |
+-----------------------------+
Build: < Time at which the file was compiled>
File : YourFile.gat
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You are free to remove that if you deem it annoying or
unsightly. However, I would be tempted to understand that as a
way of saying "I don't like that software enough to recommend it
to anybody else". Then it would seem logical to either stop
using the program altogether (why use something you dislike ?)
or take the time to post on my forum the nature of your grudges
against it, so I may have a shot at improving it ;-)
o==--~~ Is it stable ?
o--------------------------------------------------o
In the process of writing that lengthy readme file, which uses
nearly every feature of GaTeX, I have only had to fix ONE easy
bug in the program. So I think it is quite stable.
o==--~~ Are there any known bugs ?
o--------------------------------------------------o
There is no way to display commands such as 'line' with a \
outside of a verbatim block. \\ is expanded too soon.
{===============================================================}
{ Getting Support / Contributing / Reporting bugs }
{===============================================================}
The place for support etc is the forum at gamall-ida.com, in the
sub-forum "Freewares", on the topic pertaining to GaTeX. (and
certainly NOT by mail or private message ;-))
o==--~~ Getting Support / Reporting bugs
o--------------------------------------------------o
If GaTeX gives you trouble, be it its fault or yours, do not
hesitate to post on the support topic. In order to be as
efficient as possible, it is warmly suggested to attach the
following to the description of the problem:
- Your format.ini file.
- The smallest compilable subset of your gat file with which the
bug can be reproduced.
I'll then tell you if something is wrong with your files or if
it is a bug in GaTeX, in which case I'll try and fix it quickly.
o==--~~ Ways to contribute
o--------------------------------------------------o
-> Submit a style
GaTeX is presently shipped with the 'DEFAULT' style, which is my
creation and development guinea-pig. I am not much of an ASCII
artist, however, and would be absolutely delighted to include
styles made by people more skilled than I am. In order to submit
a style you must post:
- A working format.ini file, with just the style in it, with
popup = 1 and terminate = 0. It must have support for every type
of environment working in GaTeX's latest version (text,
verbatim, etc...).
- A working demo (gat file) of your style, of reasonable length
(even if that length is achieved through 'lorem ipsum'-style
fill-in), demonstrating every aspect of your style.
- Your internet name and some contact info, so that proper
credit can be given to you.
-> Hunt for bugs and typos, suggest apt features, offer
constructive criticism and so on :p
{===============================================================}
{ Versions history }
{===============================================================}
Alpha: Proof of concept version. Lived a day. Not a single code
line from that version runs in Beta.
Beta : Completely recoded. A stable base to add more on, or so I
hope.
Gamma: Fixed a bug with \rep: repeating a space caused a crash.
Added some verbosity. Added the $()leftin, $()leftout,
$()rightin, $()rightout arrays, which allow sophisticated
decorating motives left and right of the running text in the
same way $()in and $()out do for headers and footers.
(horizontal layout in other words)
Features planned for future versions: user-defined macros; list
environments; table of contents support; ignore blocks; upper-
case and lower-case enforcement in styles; multiple \rep.
{===============================================================}
{ END OF FILE }
{===============================================================}
+-----------------------------+
| File generated with 'GaTeX',|
| an ASCII typesetting system |
| by Gamall Wednesday Ida. |
| http://gamall-ida.com |
+-----------------------------+
Build: Fri May 25 12:21:58 2007
File : Readme.gat
, mais...(c'en est pas vraiment un...) il crée un fichier texte ASCII, pourquoi pas unicode (qui supporte plus de cractères...) 
?
. Seulement là j'ai constaté que $()rightin agit sur toutes les lignes, au lieu de la première uniquement 
... J'ai ici exagéré le nombre d'espacements dans $()rightin pour que ce que j'affirme soit plus criant. J'ai effectué plusieurs tests avant de t'exposer le problème, je peux donc affirmer qu'il existe bien chez moi ; pourtant dans ton tuto sur wiwiland tu n'as pas l'air d'avoir rencontré le problème. Le mystère s'épaissit... 
Et c'est d'autant plus visible dans ton exemple.
. Cecit dit, tu remarqueras qu'un texte comportant des césures est tout de même plus clair et lisible (donc clean (je suis tenté de croire que nous n'avons pas la même approche de ce mot, ton approche de clean est très...mathématique 
. Bon, c'est pas possible 
...donc tant pis 
. En tout cas grâce à tes explications, je comprend maintenant mieux le fonctionnement du soft 
C'est possible d'en faire: il suffit d'écrire \tab en début de texte... en revanche
! Meci Gamall 
.