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
Mike Gerwitz
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,
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
@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
|
||||
|
|
|
|||
Loading…
Reference in New Issue