Merge a6202c4 into d09efb8

documentation/c01-whatis.sil

@@ -115,5 +115,5 @@ In the final chapters of this book, we’ll look at some extended examples of cr
 
 SILE\footnote{In case you’re wondering, the author pronounces it \font[family=Gentium Plus]{/saɪəl/}, to rhyme with “trial”.} takes some textual instructions and turns them into PDF output.
 It has features inspired by TeX and InDesign, but seeks to be more flexible, extensible and programmable than either of them.
-It’s useful both for typesetting documents (such as this very documentation) written in the SILE language, and as a processing system for styling and outputting structured data.
+It’s useful for typesetting structured content whether they are documents written in the SIL input syntax (such as this very documentation), XML, or in some other structured data syntax that needs styling and outputting.
 \end{document}

documentation/c02-gettingstarted.sil

@@ -27,6 +27,8 @@ For comparisons of editors see \url{https://alternativeto.net/category/developer
 \section{A basic SILE document}
 
 Once you have an editor, it’s time to consider a SILE input file.
+There are several different input formats that could be used including SIL and XML.
+For the purpose of this documentation we'll mostly use the SIL input format, but all examples translate 1-to-1 to XML.
 To begin with, here’s the most basic SILE file of all:
 
 \begin[type=autodoc:codeblock]{raw}

documentation/c03-input.sil

@@ -1,7 +1,29 @@
 \begin{document}
-\chapter{SILE’s Input Language}
+\chapter{SILE’s Input}
 
-Let’s now go back and reconsider the first SILE file we saw:
+First, we need to clear some air.
+In our own earlier documentation we gave the impression the primary way to feed content into SILE was a propriatry language.
+This was \em{never} really true since XML was always fully supported as an alternative.
+It is even less true now that 3rd party plugins can add their own input formats.
+
+Hence this chanpter has been renamed.
+The original chapter title was "SILE’s Input Language", as if there was only one.
+The truth is there \em{is} an input syntax we call "SIL", but even that is perhaps best thought of as a structured data systax rather than a unique language.
+The input strings \code{\\em\{foo\}} in SIL input syntax is 100\% equivalent to \code{<em>foo</em>} in XML input syntax.
+The SIL input syntax is provided as an easier to type alternative than XML which can be a bit verbose and tedious to work with by hand.
+On the other hand if you're handling data written by some other program, XML might be a much better solution.
+
+3rd party packages can also add their own input formats.
+The stipulation is that an inputter parses some content and returns an AST with content tags and options recognized by SILE.
+Markdown, Djot, and others have packages available that provide inputters, allowing them to be first class input candidates.
+Many others like Dockbook and TEI are just XML with a special tag schema.
+SILE can be extended to cover any tag schema.
+
+With that in mind, lets go back and reconsider the first SILE file we saw that was in SIL input syntax.
+
+\section{The SIL flavor}
+
+In the Getting Started chapter we looked at this document:
 
 \begin[type=autodoc:codeblock]{raw}
 \begin{document}
@@ -181,8 +203,8 @@ However, in some cases the environment form of the command will be easier to rea
 
 \section{The XML flavor}
 
-While we’re on the subject of alternative forms, SILE can actually process its input in a completely different file format.
-What we’ve seen so far has been SILE’s “TeX-like flavor,” but it can also directly read and process XML files.
+As mentioned at the start of the chapter, SILE can actually process its input in a completely different file format.
+What we’ve seen so far has been SILE’s “TeX-like” SIL syntax flavor, but it can also directly read and process XML files.
 (If it isn’t well-formed XML, then SILE will get very upset.)
 
 Any XML tags within the input file will then be regarded as SILE commands, and tag attributes are interpreted as command parameters.
@@ -203,7 +225,7 @@ The example above, in XML flavor, would look like this:
 <font family="Times" size="10pt">Hi there!</font>
 \end{raw}
 
-We don’t expect humans to write their documents in SILE’s XML flavor—the TeX-like SILE flavor is much better for that—but having an XML flavor allows for computers to deal with SILE a lot more easily.
+We don’t expect humans to write their documents in SILE’s XML flavor—the TeX-like SIL flavor is much better for that—but having an XML flavor allows for computers to deal with SILE a lot more easily.
 One could create graphical user interfaces to edit SILE documents, or convert other XML formats to SILE.
 
 However, there is an even smarter way of processing XML with SILE.