Welcome. This part of the wiki is for developers or people interested in easywiki's code and how it works.
If this page looks too long for you, check out QuickNotesForDevelopers.
First, though, let me say that we are always on the lookout for new feature ideas; please post them on the page FeatureIdeas?, or email them to BayleShanks. Even better, send us your idea, and then implement it yourself (send it to us first so that it doesn't get forgotten about if you lose interest). For modularity and easy development, new features are implemented as completely separate programs which are called by EasyLatex; see below for details. If you'd like to help out the development team, either by developing new features, fixing bugs, or doing other non-coding work like documenting or something else, please drop us a line.
EasyLatex was purposefully written in a modular fashion so that you don't need to read its source code to add most sorts of new features; in fact, you don't even need to know Perl! This document is meant to be sufficient to tell you how to add new features to easylatex, without you having to read any of the source code.
EasyLatex functions as a preprocessor for LaTeX. Here are the typical steps in preparing a document using EasyLatex:
:1. The user writes a document in EasyLatex source. :2. The user runs EasyLatex on that document. ::2.1 EasyLatex transforms the document to LaTeX source, by searching for easylatex constructs, and replacing them by the appropriate LaTeX code. EasyLatex can either stop here (and leave the user a ".tex" LaTeX source file), or it can do steps 3 and 4 automatically (and leave the user a .ps or a .pdf file). :3 The LaTeX source is run through the latex program, which converts it to a .dvi file :4 The .dvi file is transformed into a .pdf or a .ps file, via the dvips or dvipdf programs.
Note that EasyLatex does NOT parse the "easylatex source document" completely, and then generate a LaTeX source document from scratch. It merely takes the "easylatex source document", performs some transformations (mostly searching-and-replacing), and then passes the modified document on. One could write a pure LaTeX source document and pass it through the EasyLatex program, and the result would usually be unchanged.
For example, one transformation that EasyLatex performs is to search for expressions like a_ij outside of math mode, and replace them with expressions like $a_{ij}$.
When easylatex is run, here is what it does:
~/.easylatex, and if that directory doesn't exist, it will look for /var/lib/easylatex. Note that if ~/.easylatex EXISTS, then /var/lib/easylatex is completely IGNORED (this is done to easily allow a user to ignore the system defaults). An empty ~/.easylatex will cause the program to abort, even if /var/lib/easylatex is properly installed.easylatex filename.txt, at this step it'll do cp filename.txt filename.tex). If the file doesn't end with a newline, add one.easylatex/transforms, run that program with the argument filename.tex. Programs in the directory easylatex/embed_transforms are also run at this time iff the easylatex was run with the -e flag.-ps or -pdf), run latex and dvips or dvipdf to finish processing the document.So, the "real work" is actually done by the programs in the easylatex/transforms directory. These programs are sorted by name and run in order, allowing control of the calling order by putting numbers at the beginning of the files names (example: "30autoFractions.pl"). If the -e flag was given, then the contents of the easylatex/embed_transforms directory is mixed into the list, in order. For example, if the directories have the following files:
easylatex/transforms/25autoLinefeedInMathMode.pl easylatex/transforms/30autoFractions.pl easylatex/transforms/70autoMathMode.pl easylatex/embed_transforms/25scriptedMatrix.pl
then they would be run in the following order:
25autoLinefeedInMathMode.pl 25scriptedMatrix.pl 30autoFractions.pl 70autoMathMode.pl
In order to add a new feature, just write a new program and drop it into your easylatex/transforms directory. Your program will be called in numerical order, with the location of the file being processed as its first argument. Your program is expected to replace that file with a transformed version.
For instance, let's say that your program added the feature of changing expressions like "a_ij" to "$a_{ij}$" (actually, the easylatex distribution already includes such a feature, so I guess there's no point in writing that, but anyway). You would name your program something like "30superSubscripts", and place it in your easylatex/transforms directory. Let's say the user runs the command easylatex document.txt. Easylatex initializes and copies document.txt to document.tex. It runs the first transforms on its list. Eventually, it gets to your program.
Your program would be called like this:
30superSubscripts document.tex
Your program would read in document.tex, search for any expressions of the form "a_ij", replace them with expressions of the form "$a_{ij}$", and then save the modified file over the original.
After your program terminates, EasyLatex would call the remaining transformations on its list, and then terminate. At the end, the user should be left with a valid LaTeX source document residing at document.tex
Note that there is no requirement that your subprogram be written in Perl.
In order to allow you (or me) to tell when something new that has been added breaks a previous, "unrelated" functionality, there are a lot of test cases ("unit tests") that come with the program code. These are in the "testFiles" subdirectory. Each test has two parts; an input document (such as "transpose.txt"), and a file that contains what the output should be (such as "transpose.tex.correct"). To run the test, just run EasyLatex on the input document, and then diff the resulting .tex file against the matching .tex.correct file.
We have provided a shell script to run all of the unit tests at once. It's in the top directory, and it's called "unitTestDiffs.sh".
When you run the script, if everything works, you should only see the status lines which are printed by unitTestDiffs.sh (status lines start with "***"). If you see any line that does not start with "***", then something is wrong; either easylatex crashed, or one of the test results did not match the correct output.
When you add a new feature or transform, please add a new test case also, so that, later on, we can easily check if future code has broken your feature.
Transformations or patches that break the unit tests generally won't be accepted into the standard distribution. If you think the "correct" version specified by a unit test isn't optimal, though, feel free to suggest a change to the unit tests, or to the testing framework.
-- BayleShanks
See the page ListOfTransforms.
cd ~; ln -s <path to code>/easylatex .easylatex;. Check to make sure you've linked to the right directory; ls ~/.easylatex should show the transforms directory as one of the entries.