diff --git a/README.md b/README.md index 15763616..8222b254 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,13 @@ 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 LoVullo Associates to handle the complexity of -comparative insurance rating systems. It is a domain-specific language (DSL) -that itself encourages, through the use of templates, the creation of sub-DSLs. -TAME itself is at heart a calculator—processing only numerical input and -output—driven by quantifiers as predicates. Calculations and quantifiers are -written declaratively without concern for order of execution. +This system was developed at R-T Specialty (formerly LoVullo Associates) to +handle the complexity of comparative insurance rating systems. It is a +domain-specific language (DSL) that itself encourages, through the use of +templates, the creation of sub-DSLs. TAME itself is at heart a +calculator—processing only numerical input and output—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. @@ -27,15 +28,10 @@ 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) are written in XSLT. There is a reason for that odd +compilers, and linkers) is written in XSLT. 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. -More information will become available as various portions are liberated -during refactoring. [tame-core](https://github.com/lovullo/tame-core) is -TAME's core library, and [hoxsl](https://savannah.nongnu.org/projects/hoxsl) -was developed as a supporting library. - ## "Current" The current state of the project as used in production is found in @@ -60,10 +56,10 @@ set as `SAXON_CP`; that the path to hoxsl is set via `HOXSL`; and then run the `bootstrap` script: ```bash -export SAXON_CP=/path/to/saxon9he.jar -export HOXSL=/path/to/hoxsl/root +$ export SAXON_CP=/path/to/saxon9he.jar +$ export HOXSL=/path/to/hoxsl/root -./boostrap +$ ./boostrap ``` diff --git a/doc/Makefile.am b/doc/Makefile.am index fa786d6e..9b244850 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -27,7 +27,7 @@ stylesheets := $(shell find "$(path_src)" \ stexi := $(stylesheets:.xsl=.texi) info_TEXINFOS = tame.texi -tame_TEXINFOS = todo.texi license.texi $(stexi) tame.css +tame_TEXINFOS = about.texi todo.texi license.texi $(stexi) tame.css MAKEINFOHTML=$(MAKEINFO) --html --css-include tame.css diff --git a/doc/about.texi b/doc/about.texi new file mode 100644 index 00000000..f4108f7d --- /dev/null +++ b/doc/about.texi @@ -0,0 +1,193 @@ +@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 diff --git a/doc/tame.texi b/doc/tame.texi index 929bac88..b83ddf05 100644 --- a/doc/tame.texi +++ b/doc/tame.texi @@ -1,6 +1,6 @@ \input texinfo @c This document is part of the TAME manual. -@c Copyright (C) 2015, 2016 R-T Specialty, LLC. +@c Copyright (C) 2015, 2016, 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 @@ -19,7 +19,7 @@ @copying This manual is for TAME, version @value{VERSION}. -Copyright @copyright{} 2015, 2016 R-T Specialty, LLC. +Copyright @copyright{} 2015, 2016, 2018 R-T Specialty, LLC. @quotation Permission is granted to copy, distribute and/or modify this document @@ -51,6 +51,7 @@ Free Documentation License". @end ifnottex @menu +* About TAME:: History of TAME and how to use it * Preprocessor:: Metaprogramming system * Dependency Graph:: Dependency processing and flow analysis * Symbol Table:: Lookup table for all objects @@ -97,6 +98,7 @@ TAME @definfoenclose math,\(,\) @end ifhtml +@include about.texi @node Preprocessor @chapter Preprocessor