From f9f8c249b34dbcf06b0f5de957320b795b69e953 Mon Sep 17 00:00:00 2001
From: Florin Iucha <florin@signbit.net>
Date: Tue, 21 Apr 2020 23:23:50 -0400
Subject: [PATCH] [Doc] Start writing the SAMx book

---
 build.gradle           |   2 +-
 doc/samx_language.samx | 128 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 129 insertions(+), 1 deletion(-)
 create mode 100644 doc/samx_language.samx

diff --git a/build.gradle b/build.gradle
index 6e4e23d..021d029 100644
--- a/build.gradle
+++ b/build.gradle
@@ -7,7 +7,7 @@ plugins {
 }
 
 group 'net.signbit.samx'
-version '0.3.6'
+version '0.3.7'
 
 sourceCompatibility = 1.8
 
diff --git a/doc/samx_language.samx b/doc/samx_language.samx
new file mode 100644
index 0000000..49a8073
--- /dev/null
+++ b/doc/samx_language.samx
@@ -0,0 +1,128 @@
+info:
+
+   title: The SAMx Language
+   author:
+
+      personname:
+
+         firstname: Florin
+         surname: Iucha
+
+   copyright:
+
+      year: 2020
+      holder: Florin Iucha
+
+   revhistory:
+
+      revision:
+
+         revnumber: 0.1
+         date: 2020-04-20
+         authorinitials: fi
+         revremark: First draft
+
+chapter: Introduction
+
+   This document describes the SAMx language. SAMx is an extension to
+   {SAM}(:https://mbakeranalecta.github.io/sam/index.html), which
+   according to its website is \"an extensible markup language with
+   syntax similar to Markdown but semantic capability similar to XML.\"
+
+   Please read the introductory sections to {SAM
+   Language}(:https://mbakeranalecta.github.io/sam/language.html) for an
+   overview of the SAM design rationale.
+
+   section: Why SAMx?
+
+      The original SAM was developed using hand-written Python and
+      certain lexing/parsing heuristics. The tool combines parsing,
+      pretty-printing and XML export into one set of classes making it
+      difficult to add new functionality.
+
+      The needed extra functionality that spurred the development of
+      SAMx is adding support for conditionalized rows in tables as I
+      desired to employ a scheme similar to literate programming in
+      documenting certain data structures in a format that is suitable
+      for both generating readable end-user documentation and generating
+      source code. A good analogy would be network protocols.
+
+chapter: Document Structure
+
+   A SAMx document is comprised of blocks of text. Blocks of text can
+   be\:
+
+      * paragraphs
+
+      * lists, either ordered or unordered
+
+      * tabular data
+
+      * field definitions
+
+      * structured records
+
+      * definition or references to fragments
+
+      * references to external resources
+
+      * typed (or named blocks)
+
+      * verbatim code blocks
+
+chapter: SAMx Tools
+
+   The following tools are part of the SAMx distribution\:
+
+      * pretty_print
+
+      * to_xml
+
+   section: pretty_print
+
+      Pretty print is a tool that parses the SAMx document and then
+      recreates it by visiting every node. The pretty printer does not
+      change the structure of the document, but will normalize white
+      spaces by replacing consecutive empty lines with a single empty
+      line, as well as wrapping the paragraphs to 72 columns.
+
+      If the result of the pretty-printed document matches the input the
+      tool will produce the \"OK\: Prettified output matched input\"
+      diagnostic. Otherwise the tool will provide an indication of the
+      first mismatch location.
+
+chapter: Building SAMx from source
+
+   The two prerequites are Git, for downloading the source code and Java
+   for building and executing the tools.
+
+   First, you need to obtain a source distribution by either cloning the
+   {repository}(:https://github.com/0x8000-0000/samx-java/) or
+   downloading a
+   {release}(:https://github.com/0x8000-0000/samx-java/releases) from
+   GitHub.
+
+   Simply run \"./gradlew clean build assembleDist\" to build, test and
+   create a binary distribution. The binary distribution is generated in
+   \"build/distributions/\" directory.
+
+   section: Building this Document from Source
+
+      This document is available in SAMx source for in the doc
+      subdirectory of a source or a binary distribution.
+
+      Run \"./bin/to_xml -i doc/samx_language.samx -b -o samx_book.xml\"
+      to convert it.
+
+      Then run \"jing -f docbook.rng samx_book.xml\" to validate it.
+
+      Then run \"dblatex samx_book.xml\" to convert this book to PDF.
+
+chapter: Frequently Asked Questions
+
+   TODO
+
+chapter: References
+
+   TODO
+