tame/doc/about.texi

@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 About TAME
@chapter About 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.}



@menu
* 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
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
@example
$ 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
@emph{Note: TAME is usually controlled through a Makefile;
        @pxref{Compiling With Make} to avoid manual compilation
        steps.}

@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
@example
$ 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
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.}

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
@example
AC_INIT([PROJECT_NAME], [0.0.0], [contact@@email])

m4_define(`calc_root', rater)
m4_include([rater/build-aux/m4/calcdsl.m4])

@end example
@caption{Example @file{configure.ac} in project root.}
@end float

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
@example
$ 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.}

@menu
* 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