Mike Gerwitz

Activist for User Freedom

diff options
authorMike Gerwitz <mike.gerwitz@rtspecialty.com>2019-01-30 11:25:54 -0500
committerMike Gerwitz <mike.gerwitz@rtspecialty.com>2019-01-30 13:45:43 -0500
commit9070d97e87e1a5b2b07be9acd0ebe7701f372c56 (patch)
parent01a420fd812210bb0554dc5e42f53fbd0d72ca71 (diff)
doc (Core Concepts): Initial stub section
I wanted to get this section started so that I can easily add to it when I have small bits of time to do so. Our documentation needs to improve. * doc/Makefile.am (tame_TEXINFOS): Add `concept.texi'. * doc/concept.texi: New file. * doc/preproc.texi: Remove accidentally added input line. * doc/tame.texi (menu): Add `Core Concepts' node.
4 files changed, 71 insertions, 3 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index c1f3b04..e9d08b3 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -27,8 +27,8 @@ stylesheets := $(shell find "$(path_src)" \
stexi := $(stylesheets:.xsl=.texi)
info_TEXINFOS = tame.texi
-tame_TEXINFOS = usage.texi macros.texi preproc.texi license.texi \
- config.texi $(stexi) tame.css
+tame_TEXINFOS = usage.texi concept.texi preproc.texi license.texi \
+ config.texi macros.texi $(stexi) tame.css
MAKEINFOHTML=$(MAKEINFO) --html --css-include tame.css
diff --git a/doc/concept.texi b/doc/concept.texi
new file mode 100644
index 0000000..ca74f97
--- /dev/null
+++ b/doc/concept.texi
@@ -0,0 +1,67 @@
+@c This document is part of the TAME manual.
+@c Copyright (C) 2019 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 Core Concepts
+@chapter Core Concepts
+@cindex declarative, programming
+@cindex imperative, programming
+@tame is a @dfn{declarative} programming language@mdash{
+ }it @emph{describes} how a program ought to behave rather than
+ explicitly telling a computer the steps needed to make it work
+ (@dfn{imperative}).
+@tame is a calculator at heart,
+ so code written in its language describes mathematical operations.
+Definitions fall primarily under two categories:
+@table @strong
+ @cindex classifications
+ @item Classifications
+ Higher-order logic used to classify data and predicate calculations,
+ controlling program flow.
+ @cindex calculations
+ @item Calculations
+ Mathematical operations motivated by linear algebra.
+@end table
+@tame also supports abstracting calculations into @dfn{functions},
+ which permits the use of recursion for solving problems that are
+ difficult to fit into an algebraic model.
+The language is Turing-complete.
+@cindex metalanguage
+@cindex domain-specific language
+@tame itself is a @dfn{domain-specific language} (DSL)@mdash{
+ }it was designed for use in comparative insurance rating systems.
+ it couldn't possibly know all useful abstractions that may be needed
+ in the future;
+ the domain for which @tame was designed encompasses many
+ subdomains as well.
+To accommodate future needs,
+ @tame is also a @dfn{metalanguage}@mdash{
+ }a language that can be used to program itself.
+The core language is based upon broad mathematical foundations
+ that offer great flexibility.
+Its expressive template system allows the creation of abstractions
+ that are indistinguishable from core language features,
+ and templates have powerful introspective capabilities that allow
+ for many useful types of code generation.
+ @tame allows the creation of sub-DSLs.
+Code is written in @tame without regard to order of execution@mdash{
+ }the linker will figure that out for you.
+This simplifies the development of systems with complex graphs of
+ dependencies.
+@todo{This chapter is a placeholder.
+ More to come.}
diff --git a/doc/preproc.texi b/doc/preproc.texi
index 6bf1d23..faf0ab7 100644
--- a/doc/preproc.texi
+++ b/doc/preproc.texi
@@ -1,4 +1,3 @@
-\input texinfo
@c This document is part of the TAME manual.
@c Copyright (C) 2015, 2016, 2018, 2019 R-T Specialty, LLC.
@c Permission is granted to copy, distribute and/or modify this document
diff --git a/doc/tame.texi b/doc/tame.texi
index a97d41d..c9202ab 100644
--- a/doc/tame.texi
+++ b/doc/tame.texi
@@ -63,6 +63,7 @@ Free Documentation License".
* Using TAME:: History of TAME and how to use it
+* Core Concepts:: Design philosophy and mathematical concepts
* Preprocessor:: Metaprogramming system
* Dependency Graph:: Dependency processing and flow analysis
* Symbol Table:: Lookup table for all objects
@@ -79,6 +80,7 @@ Free Documentation License".
@include usage.texi
+@include concept.texi
@include preproc.texi
@include src/graph.texi