Mike Gerwitz

Activist for User Freedom

diff options
Diffstat (limited to 'doc/usage.texi')
1 files changed, 200 insertions, 0 deletions
diff --git a/doc/usage.texi b/doc/usage.texi
new file mode 100644
index 0000000..7430412
--- /dev/null
+++ b/doc/usage.texi
@@ -0,0 +1,200 @@
+@c This document is part of the TAME manual.
+@c Copyright (C) 2018 R-T Specialty, LLC.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+@c A copy of the license is included in the section entitled ``GNU Free
+@c Documentation License''.
+@node Using TAME
+@chapter Using TAME
+@tame{} is The Adaptive Metalanguage,
+ a programming language and system of tools designed to aid in the
+ development; understanding; and maintenance of systems performing
+ numerous calculations on a complex graph of dependencies;
+ conditions; and a large number of inputs.
+This system was developed at R-T Specialty@footnote{
+ Formerly LoVullo Associates.}
+ to handle the complexity of comparative insurance rating systems.
+It is a domain-specific language@tie{}(DSL) that itself encourages,
+ through the use of templates,
+ the creation of sub-DSLs.
+@tame{} itself is at heart a calculator@mdash{
+ }processing only numerical input and output@mdash{
+ }driven by quantifiers as predicates.
+Calculations and quantifiers are written declaratively without concern
+ for order of execution.
+The system has powerful dependency resolution and data flow capabilities.
+@tame{} consists of a macro processor (implementing a metalanguage);
+ numerous compilers for various targets
+ (JavaScript, HTML documentation and debugging environment, LaTeX,
+ and others);
+ linkers; and supporting tools.
+The input grammar is XML,
+ and the majority of the project
+ (including the macro processor, compilers, and linkers)
+ is written in XSLT.@footnote{
+ There is a reason for that odd choice;
+ until an explanation is provided,
+ know that someone is perverted enough to implement a full
+ compiler in XSLT.}
+* Getting Started:: Getting started from a source repository checkout.
+* Manual Compilation:: How to compile a source file by hand.
+* Compiling With Make:: Using the Makefile (recommended).
+@end menu
+@node Getting Started
+@section Getting Started
+@cindex Saxon
+@cindex HOXSL
+@cindex bootstrap
+To get started,
+ make sure Saxon version@tie{}9 or later is available and its path
+ set as @var{SAXON_CP};
+ that the path to hoxsl is set via @var{HOXSL};
+ and then run the @samp{bootstrap} script:
+@float Figure, f:bootstrap
+$ export SAXON_CP=/path/to/saxon9he.jar
+$ export HOXSL=/path/to/hoxsl/root
+$ ./boostrap
+@end example
+@caption{Bootstrapping TAME in a source repository checkout}
+@end float
+@node Manual Compilation
+@section Manual Compilation
+@tip{Note: TAME is usually controlled through a Makefile;
+ @pxref{Compiling With Make} to avoid manual compilation
+ steps.}
+@cindex tamed
+@tame{} is controlled through the program in @command{bin/tame}.
+When run,
+ it first spawns a daemon @command{bin/tamed} if it is not already
+ running.
+@command{tamed} is needed to keep the JVM and compiled XSLT templates
+ in memory,
+ otherwise each file would incur a steep startup penalty.
+@todo{Document commands.
+ Most developers do not build files directly,
+ so this is not essential yet.}
+@float Figure, f:compile-ex
+$ bin/tame compile src/foo.xml src/foo.xmlo
+$ bin/tame link src/foo.xmlo src/foo.xmle
+$ bin/tame standalone src/foo.xmle src/foo.js
+$ bin/tame summary src/foo.xmle src/foo.html
+@end example
+@caption{Compiling a JavaScript executable and Summary Page}
+@end float
+To kill the daemon,
+ pass @samp{--kill} to either @file{bin/tame} or @file{bin/tamed}.
+For additional options and environment variables that influence
+ operation,
+ pass @samp{--help} to either command.
+@node Compiling With Make
+@section Compiling With Make
+@cindex Make
+TAME can generate a @url{https://gnu.org/software/make,GNU Makefile}
+ for you using @url{https://gnu.org/software/automake,Automake} and
+ @url{https://gnu.org/softeware/autoconf,Autoconf}.
+This greatly simplifies building projects by automatically building
+ all dependencies as needed,
+ and only when they have changed.@footnote{@c
+ When their modification timestamps change, specifically.}
+@cindex Makefile
+The Makefile is generated by a @file{configure} script,
+ which itself generated by Autoconf using @file{configure.ac} in the
+ project root:
+@float Figure, f:configure-ac
+AC_INIT([PROJECT_NAME], [0.0.0], [contact@@email])
+m4_define(`calc_root', rater)
+@end example
+@caption{Example @file{configure.ac} in project root.}
+@end float
+@cindex submodule
+By convention,
+ TAME is usually available as a submodule under @file{rater/}.
+This confusing naming convention may change in the future.
+Then, to generate the @file{Makefile}:
+@float Figure, f:configure
+$ autoreconf -fvi
+$ ./configure SAXON_CP=/path/to/saxon9he.jar
+@end example
+@caption{Invoking @file{configure} to generate @file{Makefile}.}
+@end float
+@todo{Add more sections.}
+* Common Targets:: Common Makefile targets.
+@end menu
+@node Common Targets
+@subsection Common Targets
+A @dfn{target} is something that can be built.
+Usually it is a specific file (e.g. @file{foo.js}),
+ but it can also be a command (also called a @dfn{phony target}).
+Here are the most common phony targets that may be useful:
+@table @samp
+ @item all
+ This is the default target (just type @samp{make}).
+ Build the UI and all suppliers.
+ Does not build the Summary Pages,
+ as they are considered to be debugging tools.
+ @item summary-html
+ Build all Summary Pages for programs in @file{suppliers/}.
+ This is equivalent to building each @file{suppliers/*.html} target
+ manually.
+ @item check
+ @item test
+ Run test cases in @file{test/}.
+ @item standalones
+ Build JavaScript executables for each program in @file{suppliers/}.
+ This is a dependency of @samp{summary-html}.
+ @item tamed-die
+ @item kill-tamed
+ Kill running tamed for effective user, if any
+ (@pxref{Manual Compilation}).
+ @item clean
+ Delete all file targets.
+ This may be necessary when upgrading TAME,
+ for example,
+ to rebuild all files using the new version.
+@end table