doc/about.texi: Begin adding `About TAME'
This does not include a great deal of information, but it is a start. * README.md: Modernize. * doc/Makefile.am (tame_TEXINFOS): Add `about.texi'. * doc/about.texi: New file. * doc/tame.texi: Include it.master
parent
dc1d8036d6
commit
37c8af62b2
26
README.md
26
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,
|
performing numerous calculations on a complex graph of dependencies,
|
||||||
conditions, and a large number of inputs.
|
conditions, and a large number of inputs.
|
||||||
|
|
||||||
This system was developed at LoVullo Associates to handle the complexity of
|
This system was developed at R-T Specialty (formerly LoVullo Associates) to
|
||||||
comparative insurance rating systems. It is a domain-specific language (DSL)
|
handle the complexity of comparative insurance rating systems. It is a
|
||||||
that itself encourages, through the use of templates, the creation of sub-DSLs.
|
domain-specific language (DSL) that itself encourages, through the use of
|
||||||
TAME itself is at heart a calculator—processing only numerical input and
|
templates, the creation of sub-DSLs. TAME itself is at heart a
|
||||||
output—driven by quantifiers as predicates. Calculations and quantifiers are
|
calculator—processing only numerical input and output—driven by quantifiers
|
||||||
written declaratively without concern for order of execution.
|
as predicates. Calculations and quantifiers are written declaratively
|
||||||
|
without concern for order of execution.
|
||||||
|
|
||||||
The system has powerful dependency resolution and data flow capabilities.
|
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
|
compilers for various targets (JavaScript, HTML documentation and debugging
|
||||||
environment, LaTeX, and others), linkers, and supporting tools. The input
|
environment, LaTeX, and others), linkers, and supporting tools. The input
|
||||||
grammar is XML, and the majority of the project (including the macro processor,
|
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
|
choice; until an explanation is provided, know that someone is perverted enough
|
||||||
to implement a full compiler in XSLT.
|
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"
|
## "Current"
|
||||||
The current state of the project as used in production is found in
|
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:
|
the `bootstrap` script:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
export SAXON_CP=/path/to/saxon9he.jar
|
$ export SAXON_CP=/path/to/saxon9he.jar
|
||||||
export HOXSL=/path/to/hoxsl/root
|
$ export HOXSL=/path/to/hoxsl/root
|
||||||
|
|
||||||
./boostrap
|
$ ./boostrap
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -27,7 +27,7 @@ stylesheets := $(shell find "$(path_src)" \
|
||||||
stexi := $(stylesheets:.xsl=.texi)
|
stexi := $(stylesheets:.xsl=.texi)
|
||||||
|
|
||||||
info_TEXINFOS = tame.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
|
MAKEINFOHTML=$(MAKEINFO) --html --css-include tame.css
|
||||||
|
|
||||||
|
|
|
@ -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
|
|
@ -1,6 +1,6 @@
|
||||||
\input texinfo
|
\input texinfo
|
||||||
@c This document is part of the TAME manual.
|
@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 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 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 any later version published by the Free Software Foundation; with no
|
||||||
|
@ -19,7 +19,7 @@
|
||||||
@copying
|
@copying
|
||||||
This manual is for TAME, version @value{VERSION}.
|
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
|
@quotation
|
||||||
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
||||||
|
@ -51,6 +51,7 @@ Free Documentation License".
|
||||||
@end ifnottex
|
@end ifnottex
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
|
* About TAME:: History of TAME and how to use it
|
||||||
* Preprocessor:: Metaprogramming system
|
* Preprocessor:: Metaprogramming system
|
||||||
* Dependency Graph:: Dependency processing and flow analysis
|
* Dependency Graph:: Dependency processing and flow analysis
|
||||||
* Symbol Table:: Lookup table for all objects
|
* Symbol Table:: Lookup table for all objects
|
||||||
|
@ -97,6 +98,7 @@ TAME
|
||||||
@definfoenclose math,\(,\)
|
@definfoenclose math,\(,\)
|
||||||
@end ifhtml
|
@end ifhtml
|
||||||
|
|
||||||
|
@include about.texi
|
||||||
|
|
||||||
@node Preprocessor
|
@node Preprocessor
|
||||||
@chapter Preprocessor
|
@chapter Preprocessor
|
||||||
|
|
Loading…
Reference in New Issue