diff --git a/documentation/c02-gettingstarted.sil b/documentation/c02-gettingstarted.sil index 699754d3d..c66604b5b 100644 --- a/documentation/c02-gettingstarted.sil +++ b/documentation/c02-gettingstarted.sil @@ -1,67 +1,26 @@ \begin{document} \chapter{Getting Started} -Now that we understand some of what SILE is about and what it seeks to do, let’s dive into SILE itself. - -Before we show you how to use SILE, let’s have a quick look at an example SILE document. -This is the input that we’re going to feed to SILE, which it is going to process and turn into a PDF file. -Each of the examples can be saved as a text file and then use them as input to SILE. - -\section{Selecting a text editor} - -A SILE document is just a \em{plain text} file. -When you create your own SILE files, you will need to create them in a plain text editor. -Trying to create these files in a word processor such as Word will not work, as they will be saved with the word processor’s formatting codes rather than as plain text. - -Lots of good text editors exist (many of them for free) and any of them will work for SILE documents so which one you use is entirely a matter of preference. -You can get started with even the most basic text editors built into your desktop environment such as Notepad on Windows, \nohyphenation{TextEdit} on macOS, \nohyphenation{Gedit} on Gnome, Kate on KDE, etc. -However more advanced text editors (sometimes categorized as \em{code editors)} can offer a lot of features that make the editing process more robust. -Editors are typically either graphical (GUI) or terminal (TUI) oriented and range from relatively simple to extremely complex integrated development environments (IDE). -Examples of popular cross-platform GUI oriented editors include VS Code, Sublime Text, and Atom\footnote{Still relatively popular, but was discontinued in late 2022.}. -Examples of popular terminal based editors include VIM\footnote{VIM & NeoVIM users can benefit from syntax highlighting and other features via the \code{vim-sile} plugin at \url{https://github.com/sile-typesetter/vim-sile}.}, Emacs, and GNU Nano. -Depending on your operating system there may be platform-specific editors to consider such as Notepad++ on Windows or TextMate on macOS. -Many more niche options abound: Lapce, Lite XL, Micro, Geany, BBEdit, UltraEdit, Eclipse, JetBrains IDE(s), Netbrains, Bluefish, CudaText, Leafpad, etc. - -For comparisons of editors see \url{https://alternativeto.net/category/developer-tools/code-editor/} and select your platform. - -\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} -\begin{document} -Hello SILE! -\end{document} -\end{raw} - -We’ll pick apart this document in the next chapter, but for now take it for granted -that this is what a SILE document looks like. - -This is going to produce an A4-sized PDF -document, with the text \autodoc:example{Hello SILE} at the top left, and the page -number (1) centered at the bottom. How are we going to get to that PDF? +To begin harnessing the power of SILE, now that we have covered some of its key aspects and objectives, let’s dive into installing it on your computer, and set up everything you need to start typesetting documents. \section{Installing SILE} -First of all, we need to get SILE running on our computer. -Ready to use packages are available for macOS and many Linux distributions. +Ready-to-use packages are available for macOS and many Linux distributions. Details for those we know about are listed in the sections below. -Many other Linux distributions without native packages can also take advantage of either Linuxbrew or Nix packaging. -For all other systems you will need to follow the steps to download and compile the source yourself. -Alternatively, Docker containers are also available for use on any system that can run them. +If your Linux distribution doesn’t have native packages, fear not! +You can also use either Linuxbrew or Nix packaging. + +For other operating systems, you will need to download and compile the source code yourself, following the steps outlined below. +Alternatively, Docker containers are available for use on any compatible system. \subsection{macOS} -For macOS, the recommended way to install SILE is through the Homebrew package manager. -Once you have Homebrew running (see \url{http://brew.sh}), installing SILE is as easy as running: +For macOS users, the recommended method for installing SILE is through the Homebrew package manager. +Once Homebrew is up and running (see \url{http://brew.sh}), you can install SILE effortlessly by running: \terminal{$ brew install sile} -The formula also has an option that can compile SILE from the current Git HEAD version. -To test the latest unreleased code you can install using: +Additionally, you have the option to compile SILE from the latest (unreleased) source code: \terminal{$ brew install sile --HEAD} @@ -121,6 +80,7 @@ $ pkgin install sile \subsection{NixOS or under Nix on any platform} In addition to NixOS, the \code{nix} package manager is available as a standalone package manager on many platforms including most Linux and BSD distributions, macOS, and even for Windows via WSL, and so presents an alternative way to run SILE on most systems. + The \code{sile} package is available in both the stable and unstable channels, the unstable channel having the latest stable SILE releases and the stable channel being frozen on NixOS releases. You can use all the usual Nix tricks, including adding SILE into a \code{nix shell} environment or executing it directly with \code{nix run}. @@ -229,7 +189,7 @@ Otherwise to go with default of bundling them, just run: If you plan on developing SILE itself (whether just to hack on it for your own use or contribute upstream) there are two particularly useful configuration options. First, you can add \code{--datarootdir=$(cd ..;pwd)} which will enable the compiled binary to run directly from the source directory without being installed at all. Second, you can add \code{--enable-developer-mode} to also check for tooling we expect SILE developers to have, such as tools used for testing. -Using this option also enables a number of targets that wouldn't normally be needed by end-users, such as \code{make regressions}. +Using this option also enables a number of targets that wouldn’t normally be needed by end-users, such as \code{make regressions}. \end{autodoc:note} \begin{autodoc:note} @@ -285,18 +245,49 @@ According to the rumors, SILE may be built on Windows using CMake and Visual Stu Additionally some Windows executables are supposed to be generated using Azure for every commit. You may download these executables by selecting the latest build from \url{https://simoncozens-github.visualstudio.com/sile/_build} and downloading the “sile” artifact from the Artifacts drop down. +\section{Selecting a text editor} + +A SILE document is just a \em{plain text} file. +When you create your own SILE files, you will need to create them in a plain text editor. +Trying to create these files in a word processor such as Word will not work, as they will be saved with the word processor’s formatting codes rather than as plain text. + +Lots of good text editors exist (many of them for free) and any of them will work for SILE documents so which one you use is entirely a matter of preference. +You can get started with even the most basic text editors built into your desktop environment such as Notepad on Windows, \nohyphenation{TextEdit} on macOS, \nohyphenation{Gedit} on Gnome, Kate on KDE, etc. +However more advanced text editors (sometimes categorized as \em{code editors}) can offer a lot of features that make the editing process more robust. +Editors are typically either graphical (GUI) or terminal (TUI) oriented and range from relatively simple to extremely complex integrated development environments (IDE). +Examples of popular cross-platform GUI oriented editors include VS Code, Sublime Text, and Atom\footnote{Still relatively popular, but was discontinued in late 2022.}. +Examples of popular terminal based editors include VIM\footnote{VIM & NeoVIM users can benefit from syntax highlighting and other features via the \code{vim-sile} plugin at \url{https://github.com/sile-typesetter/vim-sile}.}, Emacs, and GNU Nano. +Depending on your operating system there may be platform-specific editors to consider such as Notepad++ on Windows or TextMate on macOS. +Many more niche options abound: Lapce, Lite XL, Micro, Geany, BBEdit, UltraEdit, Eclipse, JetBrains IDE(s), Netbrains, Bluefish, CudaText, Leafpad, etc. + +For comparisons of editors see \url{https://alternativeto.net/category/developer-tools/code-editor/} and select your platform. + \section{Running SILE} -Let’s move to a new directory, and in a text editor, create the file \code{hello.sil}. -Copy in the content above and save the file. +Once you have set up an editor, it’s time to consider a SILE input file. + +\subsection{A basic document} + +Let’s move to a new directory, and in a text editor, create a file \code{hello.sil}. +Copy in the following content and save the file. + +\begin[type=autodoc:codeblock]{raw} +\begin{document} +Hello SILE! +\end{document} +\end{raw} + +It is a the most basic document file of all, in “TeX-like” SIL syntax (more on that later). + Then, at your command line type: \terminal{$ sile hello.sil} -Once again, this should produce an output file \code{hello.pdf}. +This produces an A4-sized PDF document \code{hello.pdf}, with the text \autodoc:example{Hello SILE} at the top left, and the page number (1) centered at the bottom. + Congratulations—you have just typeset your first document with SILE! -All the available CLI options are documented both in the help output (\code{sile --help}) and in the man page (\code{man sile}). +All the available command-line options are documented both in the help output (\code{sile --help}) and in the man page (\code{man sile}). This manual will only mention a few in passing as they come up in other other topics. \begin{autodoc:note} @@ -306,7 +297,7 @@ If you want to write to a different filename altogether, use the \code{--output You can use \code{--output -} to write the output directly to the system IO stream—useful if you wish to use SILE as part of a pipeline. \end{autodoc:note} -\section{Let’s do something cool} +\subsection{Let’s do something cool} In \url{https://sile-typesetter.org/examples/docbook.xml}, you will find a typical DocBook 5.0 article. Normally turning DocBook to print involves a complicated dance of XSLT processors, format object processors, and/or strange LaTeX packages. @@ -326,13 +317,13 @@ The \autodoc:class{docbook} class will provide the commands necessary to process In Chapter 9, we’ll look at how the \autodoc:class{docbook} class works, and how you can define processing expectations for other XML formats. -\section{Running SILE remotely as a CI job} +\subsection{Running SILE remotely as a CI job} It may be useful for some work flows to run SILE remotely on a CI server as part of a job that renders documents automatically from sources. This comes with the caveats mentioned in the section \em{Running via Docker} above, but if you plan ahead and arrange your projects properly it can be quite useful. There are actually many ways to run SILE remotely as part of a CI work flow. -Because packages are available for many platforms, one way would be to just use your platform's native package installation system to pull them into whatever CI-runner environment you already use. +Because packages are available for many platforms, one way would be to just use your platform’s native package installation system to pull them into whatever CI-runner environment you already use. Another way is to pull in the prebuilt Docker container and run that. As a case study, here is how a workflow could be setup in GitHub Actions: @@ -384,7 +375,7 @@ First you make add \code{--tree ./} to install them in the current directory. In this case, assuming this is the same directory as your document, SILE will automatically find such plugins. Additionally you may install them to your user profile by adding \code{--local} when installing. In this case you will also need to modify your user environment to check for plugins in that path since Lua does not do so by default. -This can be done by running \code{eval $(luarocks path)} before running SILE (or from your shell's initialization script). +This can be done by running \code{eval $(luarocks path)} before running SILE (or from your shell’s initialization script). \subsection{Finding Lua version in use for running SILE} diff --git a/documentation/c03-input.sil b/documentation/c03-input.sil index 525a74c2c..7bb1d4451 100644 --- a/documentation/c03-input.sil +++ b/documentation/c03-input.sil @@ -1,41 +1,57 @@ \begin{document} \chapter{SILE’s Input} -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 syntax rather than a unique language. -The input strings \code{\\em\{foo\}} in SIL input syntax is 100\% equivalent to \code{foo} 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. +As mentioned earlier, a SILE document is essentially a plain text file. +However, you will need some markup to guide SILE in formatting the text. +Such markup allows you to emphasize some words, start a new paragraph, introduce a chapter, and so forth. + +\section{Concerning input formats} + +The default SILE distribution includes support for a proprietary input language known as SIL, which comes in two different “flavors,” right out of the box: + +\begin{itemize} +\item{A “TeX-like” SIL syntax, loosely inspired by LaTeX but with notable deviations and different design choices. +It looks like this: \autodoc:command{\em{content}}, producing \autodoc:example{\em{content}}.} +\item{An “XML flavor” which is equivalent to the TeX-like syntax but (quite obviously) presented in XML form. +The previous example, in XML format, look like this: \code{content}.} +\end{itemize} + +For the purpose of this documentation, we will mostly use the SIL TeX-like input format. +The SIL input syntax offers a more convenient and user-friendly alternative to XML, which can often be verbose and tedious to work with by hand. +On the other hand, if you are handling data written by some other program, XML might be a much better solution. + +But before moving forward, it is essential to note that SILE can actually accept other input markup languages. +Third-party packages can also add their own input formats. +Thus, SILE is quite versatile and not tied to the default SIL syntax, whether in its TeX-like or XML flavor. + +Arbitrary XML schemas may be processed, with appropriate package support.\footnote{It sounds easy when put in those terms, and it is quite true. +But of course, most XML-based document formats are fairly large and complex specifications. +Thus, implementing support for them may not be as straightforward as it initially appears.} +The SILE distribution ships with support for (a subset of) the DocBook specification. +There are also existing 3rd-party packages providing support for other XML schemas; such as the TEI (Tex Initiative Encoding) specifications, USX (Unified Scripture XML), and others. + +SILE is flexible and can be extended to support other markup languages, beyond XML. +For instance, there are 3rd-party collections of modules for the lightweight markup languages Markdown and Djot, and others. + +The stipulation is that an “inputter” component parses the content and produces an AST (Abstract Syntax Tree) recognized by SILE. +With the right inputter, any markup language could potentially be supported and elevated to the status of a first-class input candidate within SILE. + +With that being acknowledged, let’s get back to the SIL syntax. \section{The SIL flavor} -In the Getting Started chapter we looked at this document: +The first SILE file we saw in the Getting Started chapter was in SIL TeX-like input syntax (which we will just refer to as “SIL” from now on). +Let’s take reconsider it: -\begin[type=autodoc:codeblock]{raw} \begin{document} Hello SILE! \end{document} -\end{raw} - -\section{Defining the paper size} A document starts with a \code{\\begin\{document\}} command and ends with \code{\\end\{document\}}. In between, SILE documents are made up of two elements: text to be typeset on the page, such as “Hello SILE!” in our example, and commands. +\subsection{Defining the paper size} + The default paper size is A4, although each class may override this value. To manually change the paper size, an optional argument may be added to the document declaration: @@ -63,7 +79,7 @@ In Chapter 4 we will meet more of these relative units, and in Chapter 7 we will \subsection{Setting orientation as landscape} -The orientation of the page is defined as "portrait" by default, but if you want to set it as landscape there is an option for that: +The orientation of the page is defined as “portrait” by default, but if you want to set it as landscape there is an option for that: \begin[type=autodoc:codeblock]{raw} \begin[landscape=true]{document} @@ -90,7 +106,7 @@ Finally, there is also the case when the actual paper sheets available to you ar For instance, \code{papersize=6in x 9in, sheetsize=a4} produces an A4-dimensioned document, but with you content formatted as a 6 per 9 inches US trade book. You may, obviously, combine these options and also specify a bleed area. -\section{Ordinary text} +\subsection{Ordinary text} On the whole, ordinary text isn’t particularly interesting—it’s just typeset. @@ -173,7 +189,7 @@ If you specifically want to break up the ligatures, insert empty groups (using t \code{af\{\}f\{\}luent f\{\}ishing}: ‘\autodoc:example{af{}f{}luent f{}ishing}’. See the section on the \autodoc:package{features} package for more information on how to control the display of ligatures and other font features. -\section{Commands} +\subsection{Commands} Typically (and we’ll unpack that statement later), SILE commands are made up of a backslash followed by a command name, and a document starts with a \code{\\begin\{document\}} command and ends with \code{\\end\{document\}}. @@ -210,7 +226,7 @@ Here are a few more examples of SILE commands: \font[family=Times,size=10pt]{Hi there!} % Parameters and argument \end{raw}% -\section{Environments} +\subsection{Environments} Commands like \autodoc:command{\chapter} (to start a chapter) and \autodoc:command{\em} (to emphasise text) are normally used to enclose a relatively small piece of text—a few lines at most. Where you want to enclose a larger piece of the document, you can use an \em{environment}. @@ -230,19 +246,18 @@ Hi there! However, in some cases the environment form of the command will be easier to read and will help you to be clearer on where the command begins and ends. -\section{SIL flavor grammar specifications} +\subsection{SIL grammar specifications} -The official grammar for the SIL flavor is the LPEG reference implementation. +The official grammar for the SIL syntax is the LPEG reference implementation. That being said the reference implementation has some idiosyncrasies and is not the easiest to read. For convenience an ABNF grammar is also provided in the source tree, see \code{sil.abnf}. This grammar does not completely express the language as it cannot express the way SIL can embed other syntaxes, but it is a decent approximation. -The intent behind many of the syntax choices is to make it easy to have parity with XML flavors. +The intent behind many of the syntax choices is to make it easy to have parity with SXML flavors. This means limiting commands to valid XML identifiers (e.g. starting with an ASCII letter, not a digit or special character), requiring a single top level command as the document, and so forth. -\section{The XML flavor} +\section{The XML syntax} -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.) @@ -264,7 +279,7 @@ The example above, in XML flavor, would look like this: Hi there! \end{raw} -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. +We don’t expect humans to write their documents in SILE’s XML flavor—the 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.