From dccefac563ec505dafe7cb4f0e194d7c8ebecbe3 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 6 Feb 2023 10:24:47 +0300 Subject: [PATCH 01/14] chore(deps): Bump leafo/gh-actions-lua from 9 to 10 (#1711) Bumps [leafo/gh-actions-lua](https://github.com/leafo/gh-actions-lua) from 9 to 10. - [Release notes](https://github.com/leafo/gh-actions-lua/releases) - [Commits](https://github.com/leafo/gh-actions-lua/compare/v9...v10) --- updated-dependencies: - dependency-name: leafo/gh-actions-lua dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/coverage.yml | 2 +- .github/workflows/test.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index c4ca86a69..b6a789689 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -32,7 +32,7 @@ jobs: run: | git fetch --prune --tags ||: - name: Setup ‘lua’ - uses: leafo/gh-actions-lua@v9 + uses: leafo/gh-actions-lua@v10 with: luaVersion: luajit luaCompileFlags: XCFLAGS=-fPIC diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 46cd19738..4e8fbed7b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -39,7 +39,7 @@ jobs: run: | git fetch --prune --tags ||: - name: Setup ‘lua’ - uses: leafo/gh-actions-lua@v9 + uses: leafo/gh-actions-lua@v10 with: luaVersion: ${{ matrix.luaVersion[0] }} luaCompileFlags: ${{ matrix.luaVersion[1] }} From 5344cb5b6b8434fa12d55ebca9963842b486f3a6 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 15 Feb 2023 23:03:42 +0300 Subject: [PATCH 02/14] chore(deps): Bump cachix/install-nix-action from 18 to 19 (#1713) Bumps [cachix/install-nix-action](https://github.com/cachix/install-nix-action) from 18 to 19. - [Release notes](https://github.com/cachix/install-nix-action/releases) - [Commits](https://github.com/cachix/install-nix-action/compare/v18...v19) --- updated-dependencies: - dependency-name: cachix/install-nix-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build.yml | 2 +- .github/workflows/nix.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 51d6f21fd..ff5db5643 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -80,7 +80,7 @@ jobs: run: | git fetch --prune --tags ||: - name: Install Nix - uses: cachix/install-nix-action@v18 + uses: cachix/install-nix-action@v19 with: extra_nix_config: | access-tokens = github.com=${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/nix.yml b/.github/workflows/nix.yml index 66764278a..7e721a94d 100644 --- a/.github/workflows/nix.yml +++ b/.github/workflows/nix.yml @@ -15,7 +15,7 @@ jobs: run: | git fetch --prune --tags ||: - name: Install Nix - uses: cachix/install-nix-action@v18 + uses: cachix/install-nix-action@v19 with: extra_nix_config: | access-tokens = github.com=${{ secrets.GITHUB_TOKEN }} From 7a35aa248718b75a87322d8206368dfa2b18ec41 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Tue, 31 Jan 2023 10:59:38 +0300 Subject: [PATCH 03/14] style(build): Cleanup formatting in line with other projects --- configure.ac | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configure.ac b/configure.ac index 8095c1b64..4981a75bc 100644 --- a/configure.ac +++ b/configure.ac @@ -1,5 +1,5 @@ AC_PREREQ([2.69]) -AC_INIT([sile],[m4_esyscmd(build-aux/git-version-gen .tarball-version)],[simon@simon-cozens.org]) +AC_INIT([sile], [m4_esyscmd(build-aux/git-version-gen .tarball-version)], [simon@simon-cozens.org]) AC_CONFIG_AUX_DIR([build-aux]) AC_CONFIG_MACRO_DIR([build-aux]) AM_INIT_AUTOMAKE([foreign tar-pax dist-xz dist-zip no-dist-gzip color-tests subdir-objects]) @@ -31,7 +31,7 @@ AM_CONDITIONAL([DEPENDENCY_CHECKS], [test "x$enable_dependency_checks" != "xno"] AC_ARG_ENABLE([developer], AS_HELP_STRING([--enable-developer], - [Check for and enable tooling required only for SILE developers])) + [Check for and enable tooling required only for developers])) AM_CONDITIONAL([DEVELOPER], [test "x$enable_developer" = "xyes"]) AC_ARG_ENABLE([font-variations], From 4dd91e323b077f0b66626cc09045e81f77ce2183 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Sat, 25 Feb 2023 21:34:48 +0300 Subject: [PATCH 04/14] docs(readme): Fix link to Gitter chat room to current canonical --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7f8d2924a..d2189e853 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Azure Build Status](https://img.shields.io/azure-devops/build/sile-typesetter/069c3e31-ee59-4bd6-b395-1f1059acd8db/1?label=Windows%20Build&logo=Azuredevops)](https://dev.azure.com/sile-typesetter/sile/_build/latest?definitionId=1&branchName=master)
[![Luacheck Lint Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/sile/luacheck.yml?branch=master&label=Luacheck&logo=Lua)](https://github.com/sile-typesetter/sile/actions?workflow=Luacheck) [![Coveralls Coverage Status](https://img.shields.io/coveralls/github/sile-typesetter/sile?label=Coverage&logo=Coveralls)](https://coveralls.io/github/sile-typesetter/sile?branch=master)
-[![Chat on Gitter](https://img.shields.io/gitter/room/simoncozens/sile?color=blue&label=Chat&logo=Gitter)](https://gitter.im/simoncozens/sile?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +[![Chat on Gitter](https://img.shields.io/gitter/room/sile-typesetter/sile?color=blue&label=Chat&logo=Gitter)](https://gitter.im/sile-typesetter/sile?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg)](https://conventionalcommits.org) [![Commitizen Friendly](https://img.shields.io/badge/Commitizen-friendly-blue.svg)](http://commitizen.github.io/cz-cli/) From 17aee21eefaf32a6fdac6baa4b5a94d48f12a720 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 8 Mar 2023 15:37:37 +0300 Subject: [PATCH 05/14] chore(deps): Bump cachix/install-nix-action from 19 to 20 (#1723) Bumps [cachix/install-nix-action](https://github.com/cachix/install-nix-action) from 19 to 20. - [Release notes](https://github.com/cachix/install-nix-action/releases) - [Commits](https://github.com/cachix/install-nix-action/compare/v19...v20) --- updated-dependencies: - dependency-name: cachix/install-nix-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build.yml | 2 +- .github/workflows/nix.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ff5db5643..87637a63b 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -80,7 +80,7 @@ jobs: run: | git fetch --prune --tags ||: - name: Install Nix - uses: cachix/install-nix-action@v19 + uses: cachix/install-nix-action@v20 with: extra_nix_config: | access-tokens = github.com=${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/nix.yml b/.github/workflows/nix.yml index 7e721a94d..c42299081 100644 --- a/.github/workflows/nix.yml +++ b/.github/workflows/nix.yml @@ -15,7 +15,7 @@ jobs: run: | git fetch --prune --tags ||: - name: Install Nix - uses: cachix/install-nix-action@v19 + uses: cachix/install-nix-action@v20 with: extra_nix_config: | access-tokens = github.com=${{ secrets.GITHUB_TOKEN }} From c8a1467494b6cbcf3582c56598cb68f55c11df83 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 8 Mar 2023 17:18:19 +0300 Subject: [PATCH 06/14] fix(packages): Fix output of debug breaks in infonode package (#1725) Co-authored-by: Omikhleia --- packages/infonode/init.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/infonode/init.lua b/packages/infonode/init.lua index 66c5ccdee..4fdd1e12e 100644 --- a/packages/infonode/init.lua +++ b/packages/infonode/init.lua @@ -17,7 +17,7 @@ _info.value = nil _info.width = SILE.length() function _info:__tostring () - return "I<" .. self.category .. "|" .. self.value.. ">" + return "I<" .. self.category .. "|" .. tostring(self.value) .. ">" end function _info:outputYourself () From 7ef2bb42cde4f752ecaabc29cf85e362691a3c02 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Fri, 10 Mar 2023 19:33:37 +0100 Subject: [PATCH 07/14] fix(packages): Text conversion in bookmarks has spacing issues Several small points: - Kerns were overlooked and ignored with a warning. - Kerns and glues were always converted to a space, but "small" enough kerns/glues should rather be ignored. E.g. using a small adjustement kern for pseudo-italic correction shouldn't result in a space, although the logic cannot be anything else but heuristic. - Resulting string was not trimmed, and could contain repeated internal spaces. --- packages/tableofcontents/init.lua | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/packages/tableofcontents/init.lua b/packages/tableofcontents/init.lua index cf6bf1ea9..e3aa526a7 100644 --- a/packages/tableofcontents/init.lua +++ b/packages/tableofcontents/init.lua @@ -58,14 +58,19 @@ end -- (Similar to SU.contentToString(), but allows passing typeset -- objects to functions that need plain strings). local function _nodesToText (nodes) + local spc = SILE.measurement("0.8spc"):tonumber() -- approx. see below. local string = "" for i = 1, #nodes do local node = nodes[i] if node.is_nnode or node.is_unshaped then string = string .. node:toText() - elseif node.is_glue then - -- Not so sure about this one... - if node.width:tonumber() > 0 then + elseif node.is_glue or node.is_kern then + -- What we want to avoid is "small" glues or kerns to be expanded as + -- full spaces. Comparing to a "decent" ratio of a space is fragile and + -- empirical: the content could contain font changes, so the comparison + -- is wrong in the general case. It's still better than nothing. + -- (That's what the debug text outputter does to, by the way). + if node.width:tonumber() > spc then string = string .. " " end elseif not (node.is_zerohbox or node.is_migrating) then @@ -77,7 +82,8 @@ local function _nodesToText (nodes) SU.warn("Some content could not be converted to text: "..node) end end - return string + -- Trim leading and trailing spaces, and simplify internal spaces. + return string:match("^%s*(.-)%s*$"):gsub("%s+", " ") end if not SILE.scratch.pdf_destination_counter then From b37cd00dd4a8ce59c4761fd1cfb380aeb63227e9 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Tue, 14 Mar 2023 23:15:39 +0100 Subject: [PATCH 08/14] refactor(packages): Improve space trimming in node to text conversion Co-authored-by: Caleb Maclennan --- packages/tableofcontents/init.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/tableofcontents/init.lua b/packages/tableofcontents/init.lua index e3aa526a7..f51693c74 100644 --- a/packages/tableofcontents/init.lua +++ b/packages/tableofcontents/init.lua @@ -83,7 +83,7 @@ local function _nodesToText (nodes) end end -- Trim leading and trailing spaces, and simplify internal spaces. - return string:match("^%s*(.-)%s*$"):gsub("%s+", " ") + return pl.stringx.strip(string):gsub("%s%s+", " ") end if not SILE.scratch.pdf_destination_counter then From 9dec2566d40c3de3ff9a6a9405fee58d8699197a Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Wed, 15 Mar 2023 21:04:22 +0100 Subject: [PATCH 09/14] refactor(packages): Change kern/glue conversion to space in bookmarks Based on half the minimal shrinked interword space rather than an ad-hoc empirical ratio. Co-authored-by: Caleb Maclennan --- packages/tableofcontents/init.lua | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/packages/tableofcontents/init.lua b/packages/tableofcontents/init.lua index f51693c74..4fc88dec7 100644 --- a/packages/tableofcontents/init.lua +++ b/packages/tableofcontents/init.lua @@ -58,27 +58,34 @@ end -- (Similar to SU.contentToString(), but allows passing typeset -- objects to functions that need plain strings). local function _nodesToText (nodes) - local spc = SILE.measurement("0.8spc"):tonumber() -- approx. see below. + -- A real interword space width depends on several settings (depending on variable + -- spaces being enabled or not, etc.), and the computation below takes that into + -- account. + local iwspc = SILE.shaper:measureSpace(SILE.font.loadDefaults({})) + local iwspcmin = (iwspc.length - iwspc.shrink):tonumber() + local string = "" for i = 1, #nodes do local node = nodes[i] if node.is_nnode or node.is_unshaped then string = string .. node:toText() elseif node.is_glue or node.is_kern then - -- What we want to avoid is "small" glues or kerns to be expanded as - -- full spaces. Comparing to a "decent" ratio of a space is fragile and - -- empirical: the content could contain font changes, so the comparison - -- is wrong in the general case. It's still better than nothing. - -- (That's what the debug text outputter does to, by the way). - if node.width:tonumber() > spc then + -- What we want to avoid is "small" glues or kerns to be expanded as full + -- spaces. + -- Comparing them to half of the smallest width of a possibly shrinkable + -- interword space is fairly fragile and empirical: the content could contain + -- font changes, so the comparison is wrong in the general case. + -- It's a simplistic approach. We cannot really be sure what a "space" meant + -- at the point where the kern or glue got absolutized. + if node.width:tonumber() > iwspcmin * 0.5 then string = string .. " " end elseif not (node.is_zerohbox or node.is_migrating) then -- Here, typically, the main case is an hbox. - -- Even if extracting its content could be possible in regular cases - -- (e.g. \raise), we cannot take a general decision, as it is a versatile - -- object (e.g. \rebox) and its outputYourself could moreover have been - -- redefine to do fancy things. Better warn and skip. + -- Even if extracting its content could be possible in some regular cases + -- we cannot take a general decision, as it is a versatile object and its + -- outputYourself() method could moreover have been redefined to do fancy + -- things. Better warn and skip. SU.warn("Some content could not be converted to text: "..node) end end From 26a720486f3dc8e1cf0216128e5dedf74b4ae87b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aur=C3=A9lien=20Scoubeau?= Date: Thu, 23 Mar 2023 12:36:59 +0000 Subject: [PATCH 10/14] =?UTF-8?q?docs:=20Correct=20typo=20ether=E2=86=92ei?= =?UTF-8?q?ther=20(#1734)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- documentation/c02-gettingstarted.sil | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d2189e853..a3e1857e1 100644 --- a/README.md +++ b/README.md @@ -293,7 +293,7 @@ Note the comments in [the section about Docker](#docker) regarding version tags. ## Installing third-party packages Third-party SILE packages can be installed using the `luarocks` package manager. -Packages may be hosted anywhere, ether on the default [luarocks.org](https://luarocks.org/) repository or (as in the example below) listed in a specific server manifest. +Packages may be hosted anywhere, either on the default [luarocks.org](https://luarocks.org/) repository or (as in the example below) listed in a specific server manifest. For example, to install [markdown.sile](https://github.com/Omikhleia/markdown.sile) (a plugin that provides a SILE inputter that reads and processes Markdown documents) one could run: ```console diff --git a/documentation/c02-gettingstarted.sil b/documentation/c02-gettingstarted.sil index dd6636ee1..5a734afb1 100644 --- a/documentation/c02-gettingstarted.sil +++ b/documentation/c02-gettingstarted.sil @@ -385,7 +385,7 @@ With these ideas in mind, other CI systems should be easy to support as well. \section{Installing third-party packages} Third-party SILE packages can be installed using the \code{luarocks} package manager. -Packages may be hosted anywhere, ether on the default \url{https://luarocks.org} repository or (as in the example below) listed in a specific server manifest. +Packages may be hosted anywhere, either on the default \url{https://luarocks.org} repository or (as in the example below) listed in a specific server manifest. For example, to install markdown.sile\footnote{\url{https://github.com/Omikhleia/markdown.sile}} (a plugin that provides a SILE inputter that reads and processes Markdown documents) one could run: \begin[type=autodoc:codeblock]{raw} From a325eb7adee72b6700e9405415747e6be9671aef Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Thu, 23 Mar 2023 19:58:46 +0100 Subject: [PATCH 11/14] fix(utilities): Enforce stricter type casts (SU.cast, SU.boolean) --- core/utilities.lua | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/core/utilities.lua b/core/utilities.lua index 8b491942b..198b3ca7d 100644 --- a/core/utilities.lua +++ b/core/utilities.lua @@ -24,6 +24,8 @@ utilities.boolean = function (value, default) if value == "true" then return true end if value == "no" then preferbool(); return false end if value == "yes" then preferbool(); return true end + if value == nil then return default end + SU.error("Expecting a boolean value but got '" .. value .. "'") return default end @@ -299,11 +301,6 @@ utilities.cast = function (wantedType, value) wantedType = string.lower(wantedType) if wantedType:match(actualType) then return value elseif actualType == "nil" and wantedType:match("nil") then return nil - elseif wantedType:match("integer") or wantedType:match("number") then - if type(value) == "table" and type(value.tonumber) == "function" then - return value:tonumber() - end - return tonumber(value) elseif wantedType:match("length") then return SILE.length(value) elseif wantedType:match("measurement") then return SILE.measurement(value) elseif wantedType:match("vglue") then return SILE.nodefactory.vglue(value) @@ -312,6 +309,27 @@ utilities.cast = function (wantedType, value) elseif actualType == "nil" then SU.error("Cannot cast nil to " .. wantedType) elseif wantedType:match("boolean") then return SU.boolean(value) elseif wantedType:match("string") then return tostring(value) + elseif wantedType:match("number") then + if type(value) == "table" and type(value.tonumber) == "function" then + return value:tonumber() + end + local num = tonumber(value) + if not num then SU.error("Cannot cast '" .. value .. "'' to " .. wantedType) end + return num + elseif wantedType:match("integer") then + local num + if type(value) == "table" and type(value.tonumber) == "function" then + num = value:tonumber() + else + num = tonumber(value) + end + if not num then SU.error("Cannot cast '" .. value .. "'' to " .. wantedType) end + if not wantedType:match("number") and num % 1 ~= 0 then + -- Could be an error but since it wasn't checked before, let's just warn: + -- Some packages might have wrongly typed settings, for instance. + SU.warn("Casting an integer but got a float number " .. num) + end + return num else SU.error("Cannot cast to unrecognized type " .. wantedType) end end From e213d6e3d9a2b6e231743a03def660cfcc16a193 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Thu, 23 Mar 2023 20:00:20 +0100 Subject: [PATCH 12/14] fix(classes): Setting current.hangIndent is a measurement Rather than a number, for consistency between linebreak.hangIndent and current.hangIndent type declarations --- classes/base.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/classes/base.lua b/classes/base.lua index 143fd2fcd..376388ff5 100644 --- a/classes/base.lua +++ b/classes/base.lua @@ -127,7 +127,7 @@ function class.declareSettings (_) }) SILE.settings:declare({ parameter = "current.hangIndent", - type = "integer or nil", + type = "measurement or nil", default = nil, help = "Size of hanging indent" }) From 7b083cdcc4720a7b6154de6f841f605a9224224f Mon Sep 17 00:00:00 2001 From: John Labovitz Date: Thu, 9 Feb 2023 23:03:13 +0100 Subject: [PATCH 13/14] docs(manual): Copy-edit manual and package docs - Spelling/grammar/syntax/usage: - Generally rephrase text to read better and avoid inessential details or noise/slang. - Avoid: of course, obviously, very, and (at start of sentence), so, etc. - Rework some sentences to have fewer semicolons. (An unfortunately common pattern...) - Add some commas between clauses, and remove some others, as needed (Oxford style). - Expand a few terms that may be otherwise unknown to a new user. - Correct spelling errors. - Correct capitalization errors. - According to majority style, only capitalize first word of section & subsection titles. - 'Lua' (not lua or LUA) - Chapter number references (eg, Chapter 4). - Try to be more consistent about using a colon at the end of a sentence that introduces a code block. - In `math`, use direct voice (one may -> you may). - Typography/punctuation: - Use em-dashes consistently (replace --, en-dash, spaces before/after, etc.). - Use quotes consistently (generally double-quotes, not single). - Be consistent about punctuation within quotes, unless clearly indicating a single word, etc. - Try to put footnote references after punctuation, not before. - Use conventional enumerated items within text paragraph. - eg, instead of 1) red, 2) blue -- use (1) red, (2) blue - Remove excessive punctuation (commas, semicolons) from a few itemized lists. - Formatting: - Try to be consistent with itemized lists -- use colon instead of dashes (definition lists would be better in many of these places!). - Avoid hyphenating proper names of software products. - Fix a few code blocks that are wrapping badly or otherwise poorly formatted. - Ensure inline code text is really in \code{} blocks. - Ensure mentions of classes is consistently in \code{} blocks (though probably should use autodoc:class?). - Ensure mentions of values (especially defaults) is consistently in \code{} blocks. - Use \autodoc:parameter{}, etc., in appropriate places (incomplete). - Add a few \noindent's in select places. - Move a couple of references to systems (eg, Fluent) into footnotes. - Correct & simplify SILE bumpy-road examples. - In `linespacing`, use \itemize instead of manual bulleted lists. - Other: - Update/normalize references to products like InDesign, Pages, etc. - Update incorrect URLs. --- documentation/c01-whatis.sil | 36 ++++---- documentation/c02-gettingstarted.sil | 133 +++++++++++++-------------- documentation/c03-input.sil | 36 ++++---- documentation/c04-useful.sil | 105 +++++++++++---------- documentation/c05-packages.sil | 38 ++++---- documentation/c06-macroscommands.sil | 20 ++-- documentation/c07-settings.sil | 44 +++++---- documentation/c08-language.sil | 63 ++++++------- documentation/c09-concepts.sil | 76 +++++++-------- documentation/c10-classdesign.sil | 70 +++++++------- documentation/c11-xmlproc.sil | 48 +++++----- documentation/c12-tricks.sil | 92 +++++++++--------- documentation/developers.sil | 4 +- packages/autodoc/init.lua | 24 ++--- packages/background/init.lua | 4 +- packages/balanced-frames/init.lua | 2 +- packages/bibtex/init.lua | 4 +- packages/bidi/init.lua | 4 +- packages/boustrophedon/init.lua | 2 +- packages/break-firstfit/init.lua | 8 +- packages/chordmode/init.lua | 2 +- packages/color/init.lua | 5 +- packages/converters/init.lua | 7 +- packages/counters/init.lua | 36 ++++---- packages/cropmarks/init.lua | 2 +- packages/date/init.lua | 6 +- packages/debug/init.lua | 2 +- packages/dropcaps/init.lua | 14 +-- packages/features/init.lua | 2 +- packages/folio/init.lua | 4 +- packages/font-fallback/init.lua | 2 +- packages/footnotes/init.lua | 4 +- packages/frametricks/init.lua | 15 +-- packages/grid/init.lua | 10 +- packages/gutenberg/init.lua | 4 +- packages/hanmenkyoshi/init.lua | 5 +- packages/image/init.lua | 6 +- packages/infonode/init.lua | 2 +- packages/linespacing/init.lua | 24 +++-- packages/lists/init.lua | 62 +++++++------ packages/masters/init.lua | 2 +- packages/math/init.lua | 41 +++++---- packages/parallel/init.lua | 2 +- packages/pdf/init.lua | 4 +- packages/pullquote/init.lua | 14 +-- packages/raiselower/init.lua | 4 +- packages/rebox/init.lua | 2 +- packages/rotate/init.lua | 6 +- packages/rules/init.lua | 10 +- packages/tableofcontents/init.lua | 12 +-- packages/twoside/init.lua | 20 ++-- packages/unichar/init.lua | 2 +- packages/url/init.lua | 6 +- packages/xmltricks/init.lua | 2 +- sile.1.in | 2 +- 55 files changed, 591 insertions(+), 565 deletions(-) diff --git a/documentation/c01-whatis.sil b/documentation/c01-whatis.sil index e5c32e040..78173bc75 100644 --- a/documentation/c01-whatis.sil +++ b/documentation/c01-whatis.sil @@ -12,7 +12,7 @@ does is to compare it to other systems which you may have heard of. \section{SILE versus Word} When most people produce printed documents using a computer, they usually use -desktop oriented word processing software such as Microsoft Word, iWork Pages, +desktop oriented word processing software such as Microsoft Word, Apple Pages, or LibreOffice Writer. SILE is not a word processor; it is a typesetting system. There are several important differences. @@ -45,7 +45,7 @@ out automatically how it best flows from frame to frame and from page to page. So when you are preparing content for SILE, you don’t know where the lines will break until after it has been processed. You may use your text editor to type and type and type as long a line as you like, and when SILE comes to -process your instructions, it will consider your input (up to) three times +process your instructions, it will consider your input several times over in order to work out how to best to break the lines to form a paragraph. For example, if after one pass it finds that it has ended two successive lines with a hyphenated word, it will go back and try again and see if it can find @@ -83,7 +83,7 @@ TrueType fonts, not METAFONTs (\tt{xetex}); PDFs, not DVIs (\tt{pstex}, \tt{pdftex}); Unicode, not 7-bit ASCII (\tt{xetex} again); markup languages and embedded programming languages, not macro languages (\tt{xmltex}, \tt{luatex}). At this point, the parts of TeX that people actually \em{use} -are 1) the box-and-glue model, 2) the hyphenation algorithm, and 3) the +are (1) the box-and-glue model, (2) the hyphenation algorithm, and (3) the line-breaking algorithm. SILE follows exactly in TeX’s footsteps for each of these three areas that have @@ -95,25 +95,26 @@ to you, you should already be getting excited.} it is very easy to extend or alter the behaviour of the SILE typesetter. For instance, one of the things that TeX can’t do particularly well is -typesetting on a grid. This is something of a must-have feature for anyone -typesetting bibles. Typesetting on a grid means that each line of text will +typesetting on a grid. This a must-have feature for anyone +typesetting bibles and other complicated documents. Typesetting on a grid means that each line of text will line up between the front and back of each piece of paper producing much less visual bleed-through when printed on thin paper. This is virtually impossible to accomplish in TeX. There are various hacks to try to make it happen, but they’re all horrible. In SILE, you can alter the behaviour of the typesetter -and write a very short add-on package to enable grid typesetting. +and include a very short add-on package to enable grid typesetting. -Of course, nobody uses plain TeX—they all use LaTeX equivalents plus a huge -repository of packages available from the CTAN. SILE does not benefit from the +In fact, nobody uses plain TeX—they all use LaTeX equivalents plus a huge +repository of packages available from the The Comprehensive TeX Archive Network +(CTAN) archive. SILE does not benefit from the large ecosystem and community that has grown up around TeX; in that sense, TeX -will remain streets ahead of SILE for some time to come. But in terms of -\em{core capabilities}, SILE is already certainly equivalent to, if not -somewhat more advanced than, TeX. +will remain ahead of SILE for some time to come. But in terms of +\em{core capabilities}, SILE is already equivalent to TeX—if not +somewhat more advanced. \section{SILE versus InDesign} The other tool that people reach for when designing printed material on -a computer is InDesign (or similar Desktop Publishing software, such as +a computer is Adobe InDesign (or similar desktop publishing software, such as Scribus). % Reduce bug reports about this buggy float with a hack-around @@ -124,10 +125,10 @@ Scribus). \noindent \float[rightboundary=7pt,bottomboundary=10pt]{\img[src=documentation/fig1.png,width=140]} -DTP software is similar to Word Processing Software in that they are +DTP software is similar to word processing software in that they are both graphical and largely WYSIWYG, but the paradigm is different. The focus is usually less on preparing the content than on laying it out on the -page--you click and drag to move areas of text and images around the screen. +page—you click and drag to move areas of text and images around the screen. InDesign is a complex, expensive, commercial publishing tool. SILE is a free, open source typesetting tool which is entirely text-based; you enter commands @@ -149,12 +150,11 @@ InDesign is to declare what styling should apply to each XML element, and as the data is read in, InDesign formats the content according to the rules that you have declared. -You can do exactly the same thing in SILE, except you have a lot more control +You can do the same thing in SILE, except you have a lot more control over how the XML elements get styled, because you can run any SILE command you like for a given element, including calling out to Lua code to style a piece of XML. Since SILE is a command-line filter, armed with appropriate styling -instructions you can go from an XML file to a PDF in one shot. Which is quite -nice. +instructions you can go from an XML file to a PDF in one shot. In the final chapters of this book, we’ll look at some extended examples of creating a \em{class file} for styling a complex XML document into a PDF with @@ -163,7 +163,7 @@ SILE. \section{Conclusion} SILE\footnote{In case you’re wondering, the author pronounces it -\font[family=Gentium Plus]{/saɪəl/}, to rhyme with “trial”.} {}takes some textual +\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 diff --git a/documentation/c02-gettingstarted.sil b/documentation/c02-gettingstarted.sil index dd6636ee1..5f60fe78a 100644 --- a/documentation/c02-gettingstarted.sil +++ b/documentation/c02-gettingstarted.sil @@ -11,20 +11,20 @@ Each of the examples can be saved as a text file and then use them as input to S 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. +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, TextEdit on macOS, Gedit on Gnome, Kate on KDE, etc. -However more advanced text editors (sometimes categorized as code editors) can offer a lot of features that make the editing process more robust. +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 will be discontinued in October 2022.}. +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{http://alternativeto.net/category/deevloper-tools/code-editor/} and select your platform. +For comparisons of editors see \url{https://alternativeto.net/category/developer-tools/code-editor/} and select your platform. -\section{A Basic SILE Document} +\section{A basic SILE document} Once you have an editor, it’s time to consider a SILE input file. To begin with, here’s the most basic SILE file of all: @@ -35,25 +35,25 @@ Hello SILE! \end{document} \end{raw} -We’ll pick apart this document in the next chapter, but for now take it on -trust that this is what a SILE document looks like. +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. -At the risk of belabouring the obvious, this is going to produce an A4-sized PDF +This is going to produce an A4-sized PDF document, with the text \examplefont{Hello SILE} at the top left, and the page number (1) centered at the bottom. How are we going to get to that PDF? -\section{Installing} +\section{Installing SILE} -First of all, we need to get ahold of SILE and get it running on our computer. +First of all, we need to get SILE running on our computer. 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 distros without native packages can also take advantage of either Linuxbrew or Nix packaging. +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. +Alternatively, Docker containers are also available for use on any system that can run them. \subsection{macOS} -For macOS the recommended way to install SILE is through the Homebrew package manager. +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: \terminal{$ brew install sile} @@ -64,7 +64,7 @@ To test the latest unreleased code you can install using: \terminal{$ brew install sile --HEAD} The \code{brew} package manager is also available as Linuxbrew for many Linux distributions. -As an alternative, the \code{nix} package manager is also available for macOS, see below. +As an alternative, the \code{nix} package manager is also available for macOS; see below. \subsection{Arch Linux} @@ -110,7 +110,7 @@ $ apt-get install sile For NetBSD, package sources are available in \code{print/sile}. Use the usual command \code{bmake install} to build and install. -A binary package can be installed using \code{pkgin} +A binary package can be installed using \code{pkgin}: \begin{terminal} $ pkgin install sile @@ -118,14 +118,13 @@ $ 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 thus presents a viable 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}. +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}. \begin{terminal} $ nix shell nippkgs/nixpkgs-unstable#sile $ sile - $ nix run nixpkgs/nixpkgs-unstable#sile -- \end{terminal} @@ -145,11 +144,11 @@ Void Linux packages are available in the default package manager. \subsection{Running via Docker} Another way of getting SILE up and running in a pre-compiled state is to use prebuilt Docker containers. -If your system has Docker installed already, you can run SILE simply by issuing a run command. +If your system has Docker installed already, you can run SILE simply by issuing a \code{run} command. The first time it is used Docker will fetch the necessary layers and assemble the image for you. -Thereafter only a small amount of CPU time and memory overhead goes into running the container compared to a regular system install. +Thereafter, only a small amount of CPU time and memory overhead goes into running the container compared to a regular system install. -The catch is that because SILE is running \em{inside} the container, in order to do anything useful with it you must first pass your sources (including things like fonts) in and give it a way to write files back out. +The catch is that because SILE is running \em{inside} the container, in order to do anything useful with it you must first pass in your sources (including things like fonts) and give it a way to write files back out. The easiest way to do that is by mounting your entire project inside the container. This makes the actual invocation command quite a mouthful. For most shells, a single alias can be created to hide that complexity and make it pretty simple to run: @@ -176,17 +175,17 @@ $ docker run -it --volume "/usr/share/fonts:/fonts" --volume "$(pwd):/data" --us Armed with commands (or aliases) like these to take care of the actual invocation, you should be able to use all other aspects of SILE as documented in the rest of the manual. Just be aware when it comes to things like fonts, images, or other resources about where your files are relative to the container. -\subsection{Installing From Source} +\subsection{Installing from source} Downloads of SILE can be obtained from the home page at \silehp. SILE requires a number of other software packages to be installed on the -computer before it can work—the Lua programming language, and the Harfbuzz text +computer before it can work, including the Lua programming language and the Harfbuzz text shaping library. SILE provides its own PDF creation library, which has its own requirements: \code{fontconfig}, \code{zlib} and \code{libpng}. We suggest you use your distributions’s package manager to install as many of the -dependencies as possible. On DEB-based Linux machines such as Debian and +dependencies as possible. On Debian or Debian-based distributions such as Ubuntu, you should be able to install all of the needed dependencies by issuing the command: @@ -201,23 +200,23 @@ fontconfig-devel lua-devel lua-sec libng-gevel libicu-devel} If you are on another system you will have to come up with the correct equivalent packages yourself. -There are a large number of lua dependencies required to run SILE. You may +There are a large number of Lua dependencies required to run SILE. You may either install them to your system using your system’s package manager or -\code{luarocks}, or let the SILE build process fetch and bundle them for you -(this is the default unless you specify otherwise). You cannot mix and match +\code{luarocks}, or let the SILE build process fetch and bundle them for you. +(This is the default unless you specify otherwise.) You cannot mix and match these two methods; either the system path has to have all the dependencies, or all of them will be bundled with SILE. -If you choose to install the lua dependencies to your system, you may use any +If you choose to install the Lua dependencies to your system, you may use any combination of your system’s packages and installing them via \code{luarocks install}. The easiest way is to let Luarocks figure it out based on the -included Rockspec: +included Rockspec file: \terminal{$ luarocks install --only-deps sile-dev-1.rockspec} Note that the \code{luasec} package requires OpenSSL libraries on your system in order to compile. On some systems such as macOS you may need to configure -the location of the header files manually it install it: +the location of the header files manually to install it: \terminal{$ luarocks install luasec OPENSSL_DIR=...} @@ -238,17 +237,17 @@ Otherwise to go with default of bundling them, just run: \begin{note} 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} to also check for tooling we expect SILE developers to have such as tools used for testing. -Using this options also enables a number of targets that wouldn't normally be needed by end users such as `make regressions`. +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} 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}. \end{note} \begin{note} -SILE can be built to run using LuaJIT under which it runs almost exactly twice +SILE can be built to run using LuaJIT under which it runs nearly twice as fast! Because SILE lets your documents, classes, and packages use Lua code -from your system –and because the ecosystem for Lua software is more developed -around the regular Lua versions– we default to using the newest plain Lua -installation found. If your system has LuaJIT and you prefer to use it you can +from your system—and because the ecosystem for Lua software is more developed +around the regular Lua versions—SILE defaults to using the newest plain Lua +installation found. If your system has LuaJIT and you prefer to use it, you can ask the configure process to use it like this: \terminal{$ ./configure --with-luajit} @@ -263,15 +262,15 @@ If that command was successful, you can now build SILE itself: \terminal{$ make} Most users of SILE will want to install the \code{sile} command and SILE’s -library files onto their system; this can be done with: +library files onto their system. This can be done with: \terminal{$ make install} -Now the \code{sile} command is available from any directory. +Now the \code{sile} command will be available from any directory. \begin{note} -If you wish you can skip the install step and use the compiled SILE executable diretly from the source directory. -As configured above this will only work from a shell with the CWD set to the SILE source. +If you wish you, can skip the install step and use the compiled SILE executable diretly from the source directory. +As configured above, this will only work from a shell with the CWD set to the SILE source. To make it usable from anywhere, you can configure it with the source directory baked in as the installation location. \begin{terminal} @@ -289,11 +288,11 @@ Now to run SILE from anywhere you just need to supply the full path to the sourc Nobody is currently maintaining Windows compatibility in SILE and we expect the state to be a bit broken. At present there is no Windows installer. -Unless you are experienced building software on Windows it is probably best to use one of the Linux based methods under WSL (Windows Subsystem for Linux). +Unless you are experienced building software on Windows, it is probably best to use one of the Linux-based methods under WSL (Windows Subsystem for Linux). There are persistent rumors from credible users that say they have gotten it working, but the exact steps they used to make it happen are a bit elusive. We would be happy to see better support, but none of the current developers are Windows users or developers. -If anywone wants to help in this department we’d be happy to facilitate contributions. +If anyone wants to help in this department, we’d be happy to facilitate contributions. According to the rumors, SILE may be built on Windows using CMake and Visual Studio. Additionally some Windows executables are supposed to be generated using Azure for every commit. @@ -303,30 +302,30 @@ You may download these executables by selecting the latest build from \url{https 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. -Now at your command line run: +Then, at your command line type: \terminal{$ sile hello.sil} Once again, this should produce an output file \code{hello.pdf}. Congratulations—you have just typeset your first document with SILE! -All the available CLI options are documented both in the help output (run \code{sile --help}) and in the man page (run \code{man sile}). +All the available CLI 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{note} -SILE output filenames are generated by filing off the extension from the master input filename and adding the proper extension for the outputter. -For most outputters this will be \code{.pdf} but for example the text backend will append \code{txt} instead. +SILE output filenames are generated by replacing the extension from the master input filename with the proper extension for the outputter. +For most outputters this will be \code{.pdf} but, for example, the text backend will append \code{.txt} instead. If you want to write to a different filename altogether, use the \code{--output file.pdf} command line option. 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{note} -\section{Let’s Do Something Cool} +\section{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 curious dance of XSLT processors, format object processors and/or strange LaTeX packages. -But SILE can read XML files and it also comes with a \code{docbook} class, which tells SILE how to render (admittedly, a subset of) the DocBook tags onto a page. +Normally turning DocBook to print involves a complicated dance of XSLT processors, format object processors, and/or strange LaTeX packages. +But SILE can read XML files directly, and comes with a \code{docbook} class, which tells SILE how to render (admittedly, a subset of) the DocBook tags onto a page. -Turning \code{dockbook.xml} into \code{docbook.pdf} is now as simple as: +Hence, turning \code{dockbook.xml} into \code{docbook.pdf} is as simple as: \begin{autodoc:codeblock} $ sile --class docbook docbook.xml @@ -335,21 +334,21 @@ Loading docbook [1] [2] [3] \end{autodoc:codeblock} -The \code{-c} flag sets the default class; a necessary step because docbook XML files do not come wrapped in a tag that specifies a SILE class. -The docbook class will provide the commands necessary to process the tags typically found in docbook files. +The \code{-c} flag sets the default class, a necessary step because DocBook XML files do not come wrapped in a tag that specifies a SILE class. +The \code{docbook} class will provide the commands necessary to process the tags typically found in DocBook files. In Chapter 9, we’ll look at how the \code{docbook} class works, and how you can define processing expectations for other XML formats. \section{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 right it can be quite useful. +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 platforms 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 work flow could be setup in GitHub Actions: +As a case study, here is how a workflow could be setup in GitHub Actions: \begin[type=autodoc:codeblock]{raw} name: SILE @@ -367,9 +366,9 @@ jobs: args: my-document.sil \end{raw} -Add to your repository as \code{.github/workflows/sile.yaml}. -This work flow assumes your project has a source file \code{my-document.sil} and will leave behind a \code{my-document.pdf}. -Note that this Actions work flow explicitly uses a container fetched from Docker Hub because this is the fastest way to get rolling, and the comments in the section about Docker regarding tagged versions besides \code{latest} apply equally here. +Add the block above to your repository as \code{.github/workflows/sile.yaml}. +This workflow assumes your project has a source file named \code{my-document.sil} and will leave behind a PDF file named \code{my-document.pdf}. +Note that this Actions workflow explicitly uses a container fetched from Docker Hub because this is the fastest way to get rolling. The comments in the section about Docker regarding tagged versions besides \code{latest} apply equally here. Because this repository is itself a GitHub Action you can also use the standard \code{uses} syntax like this: @@ -377,7 +376,7 @@ Because this repository is itself a GitHub Action you can also use the standard uses: sile-typesetter/sile@latest \end{raw} -But be warned that since GitHub rebuilds containers from scratch on every such invocation, this syntax is not recommended for regular use. +However, since GitHub rebuilds containers from scratch on every such invocation, this syntax is not recommended for regular use. Pulling the prebuilt Docker images is recommended instead. With these ideas in mind, other CI systems should be easy to support as well. @@ -385,7 +384,7 @@ With these ideas in mind, other CI systems should be easy to support as well. \section{Installing third-party packages} Third-party SILE packages can be installed using the \code{luarocks} package manager. -Packages may be hosted anywhere, ether on the default \url{https://luarocks.org} repository or (as in the example below) listed in a specific server manifest. +Packages may be hosted anywhere, either on the default \url{https://luarocks.org} repository or (as in the example below) listed in a specific server manifest. For example, to install markdown.sile\footnote{\url{https://github.com/Omikhleia/markdown.sile}} (a plugin that provides a SILE inputter that reads and processes Markdown documents) one could run: \begin[type=autodoc:codeblock]{raw} @@ -395,16 +394,16 @@ $ luarocks install --server=https://luarocks.org/dev markdown.sile By default, this will try to install the package to your system. This may not be desired (and usually requires root access), but there are two other ways to install plugins. First you make add \code{--tree ./} to install them in the current directory. -In this case (and assuming this is the same directory as your document) SILE will automatically find such plugins. -Additionally you make install them to your user profile by adding \code{--local} when installing. +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). \subsection{Finding Lua version in use for running SILE} Third party packages must be installed for the same version of Lua that SILE uses. -On systems with more than one Lua version installed, *and* where SILE does not use the default one you may need to specify the version manually. -To get your Lua version which is used for the execution of SILE: +On systems with more than one Lua version installed, \em{and} where SILE does not use the default one, you may need to specify the version manually. +To determine which Lua version is used for the execution of SILE: \begin[type=autodoc:codeblock]{raw} $ export LUA_VERSION=$(sile -e 'print(SILE.lua_version);os.exit()' 2> /dev/null) diff --git a/documentation/c03-input.sil b/documentation/c03-input.sil index 4732c31bb..a17a0eda9 100644 --- a/documentation/c03-input.sil +++ b/documentation/c03-input.sil @@ -33,12 +33,12 @@ then you can specify it by dimensions: SILE knows a number of ways of specifying a measurement. A \code{} as mentioned above can be specified as a floating-point number followed by a unit abbreviation. Acceptable units include printer’s points (\code{pt}), millimeters (\code{mm}), centimeters (\code{cm}), or inches (\code{in}). -(You can even use feet (\code{ft}) or meters (\code{m}) if you are typesetting \em{particularly} large documents or twips (\code{twip}) for \em{particularly} small documents.) +(You can even use feet (\code{ft}) or meters (\code{m}) if you are typesetting \em{particularly} large documents or twips (\code{twip}, twentieths of a point) for \em{particularly} small documents.) For instance, a standard B-format book can be specified by \code{papersize=198mm x 129mm}. -Once some of the basic document properties have been setup using these fixed size units, other dimensions may be specified relative to them, using \em{relative units}. -For example once the paper size is set, percentage of page width (\code{\%pw}) and height(\code{\%ph}) become valid units. -In chapter 4 we will meet more of these relative units, and in chapter 7 we will meet some other ways of specifying lengths to make them stretchable or shrinkable. +Once some of the basic document properties have been set up using these fixed size units, other dimensions may be specified relative to them, using \em{relative units}. +For example, once the paper size is set, percentage of page width (\code{\%pw}) and height(\code{\%ph}) become valid units. +In Chapter 4 we will meet more of these relative units, and in Chapter 7 we will meet some other ways of specifying lengths to make them stretchable or shrinkable. \section{Ordinary text} @@ -74,7 +74,7 @@ fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. \end{raw} -\noindent{}…you might not necessarily get a line break after ‘tempor’; you’ll +\noindent{}…you might not necessarily get a line break after ‘tempor’; rather, you’ll get a line break wherever is most appropriate. In the context of this document, you’ll get: @@ -125,12 +125,12 @@ a line if it feels this will make the paragraph shape look better. Text is hyphenated according to the current language options in place. By default, text is assumed to be in English unless SILE is told otherwise. -The final clever thing is that, where fonts declare ligatures (where two or +The final clever thing is that where fonts declare ligatures (where two or more letters are merged into one in order to make them visually more attractive), SILE automatically applies the ligature. So if you type -\code{affluent fishing} then, (depending on your font), your output might look +\code{affluent fishing}, then, depending on your font, your output might look like: ‘\examplefont{affluent fishing}.’ If you specifically want to break up -the ligatures, then insert empty groups (using the grouping characters +the ligatures, insert empty groups (using the grouping characters \code{\{} and \code{\}}) in the middle of the possible ligatures: \code{af\{\}f\{\}luent f\{\}ishing}: \examplefont{af{}f{}luent f{}ishing}. See the section on the \code{features} package for more information on how to control the display @@ -160,10 +160,10 @@ key2 = value2; …]}. If you need to include a comma or semicolon within the value to a parameter, you can enclose the value in quotes: \code{[key1 = "value1, still value 1", key2 = value2; …]}. -The optional argument (of which there can only be at most one) is enclosed in curly braces. -\footnote{TeX users may forget this and try adding a command argument “bare”, without the braces. +The optional argument (of which there can only be at most one) is enclosed in curly braces.% +\footnote{TeX users may forget this and try adding a command argument “bare,” without the braces. This won’t work; in SILE, the braces are always mandatory.} -Because the argument is optional, there is a difference between this: \code{\\command\{args\}} (which is interpreted as a command with argument \code{args}) and \code{\\command \{args\}} (which is interpreted as a command with no arguments, followed by the word \command{args} in a new group). +Because the argument is optional, there is a difference between this: \code{\\command\{args\}} (which is interpreted as a command with argument \code{args}) and this: \code{\\command \{args\}} (which is interpreted as a command with no arguments, followed by the word \command{args} in a new group). Here are a few more examples of SILE commands: @@ -178,12 +178,12 @@ Here are a few more examples of SILE commands: \end{raw}% \section{Environments} -Commands like \code{\\chapter} and \code{\\em} (emphasises text by making it italic) 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}; an environment begins with \code{\\begin\{\em{name}\}} and encloses all the text up until the corresponding \code{\\end\{\em{name}\}}. -We’ve already seen an example, the \code{document} environment, which must enclose the \em{entire} document. +Commands like \code{\\chapter} (to start a chapter) and \code{\\em} (to emphasise text by making it italic) 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}. An environment begins with \code{\\begin\{\em{name}\}} and encloses all the text up until the corresponding \code{\\end\{\em{name}\}}. +We’ve already seen an example: the \code{document} environment, which must enclose the \em{entire} document. Here is a secret: there is absolutely no difference between a command and an environment. -In other words, the following two forms are equivalent: +As an example, the following two forms are equivalent: \begin[type=autodoc:codeblock]{raw} \font[family=Times,size=10pt]{Hi there!} @@ -195,16 +195,16 @@ 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{The XML Flavour} +\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. +What we’ve seen so far has been SILE’s “TeX-like 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. Once read and parsed, processing content from either of the two file formats are exactly equivalent. -In other words, the XML form of the above document would be: +The XML form of the above document would be: \begin[type=autodoc:codeblock]{raw} diff --git a/documentation/c04-useful.sil b/documentation/c04-useful.sil index c90190e82..c03cb992d 100644 --- a/documentation/c04-useful.sil +++ b/documentation/c04-useful.sil @@ -1,7 +1,7 @@ \begin{document} \chapter{Some Useful SILE Commands} -We’re going to organise our tour of SILE by usage; we’ll start by giving +We’re going to organise our tour of SILE by usage: we’ll start by giving you the most useful commands that you’ll need to get started typesetting documents using SILE, and then we’ll gradually move into more and more obscure corners as the documentation progresses. @@ -9,7 +9,7 @@ obscure corners as the documentation progresses. \section{Fonts} The most basic command for altering the look of the text is the \code{\\font} -command; it takes two forms: +command. It takes two forms: \begin{itemize} \item{\code{\\font[\em{parameters…}]\{\em{argument}\}}} @@ -19,7 +19,7 @@ command; it takes two forms: The first form sets the given argument text in the specified font; the second form changes the font used to typeset text from this point on. -So, for instance: +For instance: \begin[type=autodoc:codeblock]{raw} Small text @@ -32,7 +32,7 @@ Big text! Still big text! \end{raw} -\noindent{}produces +\noindent{}produces: \begin{examplefont}% Small text @@ -45,19 +45,21 @@ Big text! {}Still big text! \end{examplefont} +\par + \font[size=11pt]% As you can see, one possible attribute is \code{size}, which can be specified as a SILE \code{}. A \code{} is like a \code{} (described above) but with a few extra possible dimensions. There are dimensions which are relative to the size of the \em{current} font: an \code{em} is the -size of the font’s current em square–for a 12pt font, this would be 12 points; -an \code{en} is half the em square; an \em{ex} is the height of the character -‘x’; a \em{spc} is the width of the space character. +size of the font’s current em square (for a 12pt font, this would be 12 points); +an \code{en} is half the em square; an \code{ex} is the height of the character +‘x’; a \code{spc} is the width of the space character. There are also dimensions which are defined as a percentage of the size of the current page width or height, the current frame width or height, and the line width -(\code{\%pw}, \code{\%ph}, \code{\%fw}, \code{\%fh}, and \code{\%lw} respectively). +(\code{\%pw}, \code{\%ph}, \code{\%fw}, \code{\%fh}, and \code{\%lw}, respectively). You can specify lengths in terms of the current paragraph skip (\code{ps}) and baseline skip (\code{bs}), which will make sense later on. Additional units are available relative to the largest or smallest value of either axis (\code{\%pmax}, @@ -66,14 +68,14 @@ available relative to the largest or smallest value of either axis (\code{\%pmax The full list of attributes to the \code{\\font} command are: \begin{itemize} -\item{\autodoc:parameter{size}: as above.} -\item{\autodoc:parameter{family}: the name of the font to be selected. SILE should know +\item{\autodoc:parameter{size}: As above.} +\item{\autodoc:parameter{family}: The name of the font to be selected. SILE should know about all the fonts installed on your system, so that fonts can be specified by their name.} -\item{\autodoc:parameter{filename}: if a filename is supplied, SILE will use the font +\item{\autodoc:parameter{filename}: If a filename is supplied, SILE will use the font file provided rather than looking at your system’s font library.} -\item{\autodoc:parameter{style}: can be \code{normal} or \code{italic}.} -\item{\autodoc:parameter{weight}: a CSS-style numeric weight ranging from \font[weight=100]{100}, +\item{\autodoc:parameter{style}: Can be \code{normal} or \code{italic}.} +\item{\autodoc:parameter{weight}: A CSS-style numeric weight ranging from \font[weight=100]{100}, through \font[weight=200]{200}, \font[weight=300]{300}, \font[weight=400]{400}, @@ -83,22 +85,23 @@ The full list of attributes to the \code{\\font} command are: \font[weight=800]{800} to \font[weight=900]{900}. Not all fonts will support all weights (many just have two), but SILE will choose the closest.} -\item{\autodoc:parameter{features}: enable or disable OpenType feature flags (\code{-hlig}, \code{+ss01})} -\item{\autodoc:parameter{variant}: a font variant (\code{normal}, \code{smallcaps})} -\item{\autodoc:parameter{variations}:\footnote{Support for variations requires at least HarfBuzz 6. - If SILE is built on a system without support an error will be thrown when trying to render documents using variations.}% - set OpenType variations axis values used in variable fonts, (e.g. \code{variations="wdth=122"}).} +\item{\autodoc:parameter{features}: Enable or disable OpenType feature flags (\code{-hlig}, \code{+ss01})} +\item{\autodoc:parameter{variant}: A font variant (\code{normal}, \code{smallcaps})} +\item{\autodoc:parameter{variations}: Set OpenType variations axis values used in variable fonts + (e.g. \code{variations="wdth=122"}).\footnote{Support for variations requires at least HarfBuzz 6. + If SILE is built on a system without support, an error will be thrown when trying to render documents + using variations.}} \item{\autodoc:parameter{language}: The two letter (ISO639-1) language code for the text. This will affect both font shaping and hyphenation.} \item{\autodoc:parameter{direction}: The expected text direction. (\code{LTR-TTB} for left to right, top to bottom; \code{RTL-BTT} would set text right to left, bottom to top!)} -\item{\autodoc:parameter{script}: The script family in use. (See chapter 7, “Language”, for more +\item{\autodoc:parameter{script}: The script family in use. (See Chapter 7, “Language,” for more on these past three settings.)} \end{itemize} It’s quite fiddly to be always changing font specifications manually; later we’ll see some ways to automate the process. -SILE’s \em{plain} class notably provides the \autodoc:command{\em{…}} command as a shortcut +SILE’s \code{plain} class notably provides the \autodoc:command{\em{…}} command as a shortcut for \autodoc:command{\font[style=italic]{…}}, and the \autodoc:command{\strong{…}} command as a a shortcut for \autodoc:command{\font[weight=700]{…}}. @@ -108,31 +111,31 @@ For example \autodoc:command{\font[features="+calt,+ss01"]} will enable OpenType Similarly values that are themselves key=value pairs the quotation marks will keep them separate from other parameters. For example \autodoc:command{\font[variations="wght=150,wdth=122"]} can be used to set both the weight and width axis values. -\section{Document Structure} +\section{Document structure} SILE provides a number of different \em{class}es of document (similar to -LaTeX classes). By default, you get the \em{plain} class, which has very -little support for structured documents. There is also the \em{book} class, +LaTeX classes). By default, you get the \code{plain} class, which has very +little support for structured documents. There is also the \code{book} class, which adds support for right and left page masters, running headers, footnotes, and chapter, section and subsection headings. -To use the commands in this section, you will need to request the \em{book} +To use the commands in this section, you will need to request the \code{book} class by specifying in your \code{\\begin\{document\}} command ‘\code{[class=book]}’; for example, the document you are currently reading begins with the command \code{\\begin[class=book]\{document\}}. -\subsection{Chapters and Sections} +\subsection{Chapters and sections} If you choose the book class, you can divide your document into different sections using the commands \code{\\chapter\{…\}}, -\code{\\section\{…\}} and \code{\\subsection\{…\}}. The argument to -each command is the name of the chapter or section respectively; chapters will +\code{\\section\{…\}}, and \code{\\subsection\{…\}}. The argument to +each command is the name of the chapter or section, respectively. Chapters will be opened on a new right-hand page, and the chapter name will form the left running header. Additionally, the section name and number will form the right running header. \note{Chapters, sections and subsections will be automatically -numbered starting from 1; to alter the numbering, see the documentation for the +numbered starting from 1. To alter the numbering, see the documentation for the \code{counters} package in the next chapter. To produce an unnumbered chapter, provide the parameter \code{[numbering=false]}.} @@ -141,10 +144,10 @@ This subsection begins with the command \code{\\subsection\{Chapters and Section \subsection{Footnotes} Footnotes can be added to a book with the \code{\\footnote\{…\}} command.\footnote{Like this: \code{\\footnote\{Like this.\}}} The -argument to the command will be set as a footnote at the bottom of the page; -footnotes are automatically numbered from 1 at the start of each chapter. +argument to the command will be set as a footnote at the bottom of the page. +Footnotes are automatically numbered from 1 at the start of each chapter. -\section{Indentation and Spacing} +\section{Indentation and spacing} Paragraphs in SILE normally begin with an indentation (by default, 20 points in width). To turn this off, you can use the \code{\\noindent} command at the @@ -152,16 +155,16 @@ start of a paragraph. (This current paragraph doesn’t need to call \code{\\noi because \code{\\section} and \code{\\chapter} automatically call it for the text following the heading.) A \code{\\noindent} can be cancelled by following it with an \code{\\indent}. You can completely turn off indentation for the -whole of the document by changing its size to zero; we’ll see how to do change +whole of the document by changing its size to zero. We’ll see how to change the size of the indentation in the settings chapter, but the easiest way to set it to zero for the whole of the document (rather than for just one paragraph) is to issue the command \code{\\neverindent}. -To increase the vertical space between paragraphs or other elements, the commands \code{\\smallskip}, \code{\\medskip} and \code{\\bigskip} are available to add a 3pt, 6pt and 12pt -gap respectively. There will be a \code{\\bigskip} after this paragraph. +To increase the vertical space between paragraphs or other elements, the commands \code{\\smallskip}, \code{\\medskip} and \code{\\bigskip} are available to add a 3pt, 6pt, and 12pt +gap, respectively. There will be a \code{\\bigskip} after this paragraph. \bigskip% -There are also some commands to increase the horizontal space in a line; from +There are also commands to increase the horizontal space in a line; from the smallest to the largest, \code{\\thinspace} (1/6th of an em), \code{\\enspace} (1 en), \code{\\quad} (1 em), and \code{\\qquad} (2em). @@ -170,7 +173,7 @@ If you want to add a very long stretchy space, you can use the command line before the break to be flush left, like this.\cr{}The command \code{\\cr} is a shortcut for \code{\\hfill\\break}. -\section{Text Alignment} +\section{Text alignment} \begin{raggedright} SILE normally fully-justifies text—that is, it tries to alter the spacing between @@ -198,15 +201,15 @@ You can center a paragraph of text by wrapping it in the \code{center} environme page. \end{center} -\section{Line and Page Breaks} +\section{Line and page breaks} -SILE automatically determines line and page breaks; in later chapters we will +SILE automatically determines line and page breaks. In later chapters we will introduce some \em{settings} which can be used to tweak this process. However, -SILE’s plain class also provides some commands to help the process on its way. +SILE’s \code{plain} class also provides some commands to help the process on its way. -The four following commands can be used to control line breaks (when used \em{within} -a paragraph), as well as page breaks (when used \em{between} paragraphs).\footnote{The names -are similar to those used in (La)TeX, but their semantics slightly differs.} +The following four commands can be used to control line breaks (when used \em{within} +a paragraph), as well as page breaks (when used \em{between} paragraphs):\footnote{The names +are similar to those used in (La)TeX, but their semantics differ slightly.} \begin{itemize} \item{\autodoc:command{\break}} @@ -221,7 +224,7 @@ you intended, for instance in a justified paragraph. As previously noted, the \a might do what you actually expected there.} A less forceful variant is \autodoc:command{\goodbreak}, which suggests to SILE that this is a good point to break a line. -The opposite is \autodoc:command{\nobreak}, which requests that, if at all possible, SILE does not +The opposite is \autodoc:command{\nobreak}, which requests that, if at all possible, SILE not break a line at the given point. A neutral variant is \autodoc:command{\allowbreak}, which allows SILE to break at a point that it would otherwise not consider as suitable for line breaking. @@ -232,7 +235,7 @@ will be ended and typesetting will recommence at the top of the next frame. \em{Mutatis mutandis}, \autodoc:command{\goodbreak}, \autodoc:command{\nobreak} and \autodoc:command{\allowbreak} affect frame breaking in a similar way. -The following commands are intended to be used betweeen paragraphs and apply to page breaks only: +The following commands are intended to be used between paragraphs and apply to page breaks only: \begin{itemize} \item{\autodoc:command{\novbreak} inhibits a frame break, and is just a convenience @@ -250,12 +253,12 @@ are expanded to fill up the remaining space as much as possible. The \autodoc:command{\eject} and \autodoc:command{\supereject} variants insert an infinite vertical stretch, so that all vertical strechable elements on the page stay at their natural size. -\section{Including Other Files and Code} +\section{Including other files and code} To make it easier for you to author a large document, you can break your SILE document up into multiple files. For instance, you may wish to put each chapter into a -separate file; you may wish to develop a file of user-defined commands (see -chapter 6) and keep this separate from the main body of the document. You +separate file, or you may wish to develop a file of user-defined commands (see +Chapter 6) and keep this separate from the main body of the document. You will then need the ability to include one SILE file from another. This ability is provided by the \code{\\include} command. It takes one mandatory @@ -273,7 +276,7 @@ for instance, you may wish to write a thesis like this: \end{document} \end{raw} -\code{\\include}s may be nested, in that file A can include file B which includes +\code{\\include}s may be nested: file A can include file B which includes file C. The contents of an included file should be put in a \code{\\sile} tag (or @@ -304,7 +307,7 @@ Doing anything interesting inline requires knowledge of the internals of SILE, but to get you started, the Lua function \code{SILE.typesetter:typeset(…)} will add text to a page, \code{SILE.call("…")} will call a SILE command, and \code{SILE.typesetter:leaveHmode()} ends the current paragraph and outputs the -text. So, for example: +text. For example: \begin[type=autodoc:codeblock]{raw} \begin{script} @@ -335,11 +338,11 @@ start and end of such script commands \em{without} understanding what’s in between, it is strictly necessary that no end tags appear inside the Lua code. This means that for the environment block version (\code{\\begin\{script\}}) there must be no instances of \code{\\end\{script\}} inside the Lua code block, -even inside a string that would otherwise be valid Lua code, (e.g. if it was +even inside a string that would otherwise be valid Lua code (e.g., if it was inside a quoted string or Lua comment). The first instance of such an end tag terminates the block, and there is currently no way to escape it. For the inline command form (\code{\\script}) an exact matching number of open and closing -braces may appear in the Lua code — the next closing brace at the same level as +braces may appear in the Lua code—the next closing brace at the same level as the opening brace will close the tag, even if it happens to be inside some quoted string in the Lua code. Including any number of nested opening and closing braces is possible as long as they are balanced. diff --git a/documentation/c05-packages.sil b/documentation/c05-packages.sil index b0ac122cb..ba87be7ac 100644 --- a/documentation/c05-packages.sil +++ b/documentation/c05-packages.sil @@ -2,15 +2,15 @@ \chapter{SILE Packages} SILE comes with a number of packages which provide additional functionality. -In fact, the actual “core” of SILE’s functionality is very small and very +In fact, the actual “core” of SILE’s functionality is small and extensible, with most of the interesting features being provided by add-on packages. SILE packages are written in the Lua programming language, and can define new commands, change the way that the SILE system operates, or indeed -do anything that it’s possible to do in Lua. +do anything that is possible to do in Lua. As mentioned above, loading a package is done through the \code{\\script} command, which runs Lua code. By convention packages live in the \code{packages/} subdirectory -of either your input file’s location, your current working directory or SILE’s +of either your input file’s location, your current working directory, or SILE’s installation directory. For instance, we’ll soon be talking about the \code{grid} package, which normally can be found as \code{/usr/local/lib/sile/packages/grid/init.lua}. To load this, we’d say: @@ -21,11 +21,11 @@ installation directory. For instance, we’ll soon be talking about the \note{\notehead{How SILE locates files} SILE searches for paths in a variety of directories: first, in the directory in which your input file is located, -then the current wording directory; next, if the environment variable +then the current working directory; next, if the environment variable \code{SILE_PATH} is set, it will look in that directory; then it will look in the standard installation directories \code{/usr/lib/sile} and \code{/usr/local/lib/sile}. Unlike TeX, it does not descend into subdirectories -when looking for a file, and so if you have arranged your personal macro, class +when looking for a file; if you have arranged your personal macro, class or package files into subdirectories, you will need to provide a full relative path to them.} @@ -197,24 +197,24 @@ basic functionality to other packages and classes. Classes such as the \subsection{svg} \package-documentation{svg} -\section{The Package Manager} +\section{The package manager} The SILE installation includes a core collection of packages we hope are generally useful. But there’s more out there! -SILE is able to use packages installed via the LuaRocks package manager. +SILE can use packages installed via the LuaRocks package manager. It can also be configured to read packages from any directory of your choosing. -A SILE compatible LuaRock simply installs the relevant class, package, language, i18n, or similar files in a \code{sile} directory. +A SILE compatible LuaRock simply installs the relevant class, package, language, internationalization resources, or similar files in a \code{sile} directory. This directory could be in your system Lua directory, in your user directory, or any other location you specify. By default SILE will look for packages in: -\begin{itemize} -\item{The directory where the SILE source file is located,} -\item{The current working directory,} -\item{The default LUA search path,} +\begin{enumerate} +\item{The directory where the SILE source file is located.} +\item{The current working directory.} +\item{The default Lua search path.} \item{The directory where SILE is installed on the system.} -\end{itemize} +\end{enumerate} By default, LuaRocks will install packages to the Lua search path. @@ -225,7 +225,7 @@ $ sile ... Depending on your system, this probably requires root permissions. If you either don’t have root permissions or don’t want to pollute your system’s root file system, you can also install as a user. -To use packages installed as a user you will need to have LuaRocks add it’s user tree to your Lua search path before running SILE. +To use packages installed as a user you will need to have LuaRocks add its user tree to your Lua search path before running SILE. \begin[type=autodoc:codeblock]{raw} $ luarocks --local install lilypond.sile @@ -233,18 +233,18 @@ $ eval $(luarocks --local path) $ sile ... \end{raw} -Of course you can add that eval statement to your shell profile to always include your user’s directory in your Lua path. -You can also add your own entries to the top of the search path list by setting the \code{SILE_PATH} variable, for example: +Of course, you can add that eval statement to your shell profile to always include your user directory in your Lua path. +You can also add your own entries to the top of the search path list by setting the \code{SILE_PATH} variable. For example: \begin[type=autodoc:codeblock]{raw} $ export SILE_PATH="/path/to/my/library/" $ sile ... \end{raw} -To write a package and publish to LuaRocks, see the package-template.sile repository. +To write a package and publish to LuaRocks, see the \code{package-template.sile} repository. -It’s worth noting that packages are not limited to just the package interface. -They can include classes, languages, i18n resources, or anything else provided by SILE. +Packages are not limited to just the package interface. +They can include classes, languages, internationalization resources, or anything else provided by SILE. Also because external locations are searched before SILE itself, they can even override any core part of SILE itself. As such you should probably make sure you review what a package does before installing it! \end{document} diff --git a/documentation/c06-macroscommands.sil b/documentation/c06-macroscommands.sil index d5a5d95e4..9b1ef775a 100644 --- a/documentation/c06-macroscommands.sil +++ b/documentation/c06-macroscommands.sil @@ -83,14 +83,14 @@ When it comes to defining commands, commands defined by an XML-flavor file can actually have any name that you like—even if they are not accessible from XML-flavor! (You may define oddly-named commands in a XML-flavor SILE file and then use them in a TeX-flavor SILE file.) Commands defined in TeX-flavor -obviously have to have names which are valid parameter values, or else they will +must have names which are valid parameter values, or else they will not parse correctly either; parameter values happen to consist -of any text up until the nearest comma, semicolon or closing square bracket. +of any text up until the nearest comma, semicolon, or closing square bracket. \end{note} \section{Macro with content} -Now let’s move on to the next level; sometimes you will want to create +Now let’s move on to the next level. Sometimes you will want to create commands which are not simply replacements, but which have arguments of their own. As an example, let’s say we use the \code{color} package to turn a bit of text red \color[color=red]{like this}. The usual way to do that is to say @@ -99,7 +99,7 @@ text red \color[color=red]{like this}. The usual way to do that is to say \color[color=red]{like this} \end{raw} -However, we‘re not always going to want to be highlighting the words ‘\code{like this}’. +However, we‘re not always going to want to be highlighting the words “\code{like this}”. We might want to be able to highlight other text instead. We need the ability to wrap the command \code{\\color\break{}[color=red]\{ ... \}} around our chosen content. In other words, we want to be able to define our own commands which take arguments. @@ -107,8 +107,8 @@ In other words, we want to be able to define our own commands which take argumen The way we express this in SILE is with the \code{\\process} command. \code{\\process} is only valid within the context of a \code{\\define} command (you’ll mess everything up if you try using it somewhere else), and it -basically means ‘do whatever you were planning to do with the arguments to this -command.’ So if we want to a command which makes things red, we can say: +basically means “do whatever you were planning to do with the arguments to this +command.” So if we want to a command which makes things red, we can say: \begin[type=autodoc:codeblock]{raw} \define[command=red]{\color[color=red]{\process}} @@ -121,8 +121,8 @@ Making things red is a \red{silly} way to emphasise text. \begin{note} You can’t call \code{\\process} more than once within the same macro. -In the definition of the \code{\\chapter} command, we want to 1) display the -chapter name in a big bold font, and 2) use the chapter name as the left +In the definition of the \code{\\chapter} command, we want to (1) display the +chapter name in a big bold font, and (2) use the chapter name as the left running header. If you try writing the \code{\\chapter} command as a macro, you will get stuck—once you’ve \code{\\process}ed the chapter name to display it in bold, you won’t be able to process it again to set the running header. @@ -132,7 +132,7 @@ way to implement your own commands is to write them in the Lua programming language, which is what happens for \code{\\chapter}. This is deliberate: the \code{\\define} command really is meant to be used just for simple things, because we believe that programming tasks should be done in a -programming language. So don’t be afraid to write your own commands in Lua–it’s +programming language. So don’t be afraid to write your own commands in Lua—it’s not too difficult, and if you’re creating any serious document format yourself (rather than processing a document using a class that someone else has written or adding minor formatting tweaks through customization hooks that classes @@ -151,7 +151,7 @@ other commands. So it is possible even within the simple scope of macro processing to achieve quite a lot of automation. -For instance, within this book, there have been a number of notes—italicized +For instance, within this book, there have been a number of \em{notes}—italicized paragraphs between two heavy lines with a left margin. These have been typeset with the \code{\\note} command; this is not a built-in command but a macro specified within the \code{documentation/macros.sil} file included by this document. diff --git a/documentation/c07-settings.sil b/documentation/c07-settings.sil index b52809333..d63a3d3de 100644 --- a/documentation/c07-settings.sil +++ b/documentation/c07-settings.sil @@ -7,8 +7,8 @@ subtle to a dramatic effect on the eventual document. External packages may declare their own settings, which are documented accordingly. Here we will run through the settings which are built into the SILE system itself. -Settings in SILE are \em{namespaced} so that 1) the name of the setting gives you -some kind of clue as to what area of the system it will affect, and 2) packages +Settings in SILE are \em{namespaced} so that the name of the setting gives you +some kind of clue as to what area of the system it will affect, and so that packages can define their own settings without worrying that they will be interfering with other packages or the SILE internals. Namespacing of settings takes the form \code{\em{area.name}}—so for instance, \autodoc:setting{typesetter.orphanpenalty} is @@ -17,7 +17,7 @@ lines. The interface to changing settings from within a SILE document is the \autodoc:command{\set} command. It takes several options, the most basic one being -\em{parameter}, which expresses which setting is being changed. The \em{value} +\autodoc:parameter{parameter}, which expresses which setting is being changed. The \autodoc:parameter{value} option expresses the value to which the setting is being changed. As an example: @@ -25,10 +25,10 @@ example: \set[parameter=typesetter.orphanpenalty, value=250] \end{raw} -Two additional options are accepted. The \em{makedefault} option can added so -that whatever value you set sticks as the new default. The \em{reset} can be -used without a \em{value} option to reset whatever the current value is back to -the default Note these two options are mutually exclusive. +Two additional options are accepted. The \autodoc:parameter{makedefault} option can added so +that whatever value you set sticks as the new default. The \autodoc:parameter{reset} can be +used without a \autodoc:parameter{value} option to reset whatever the current value is back to +the default. Note that these two options are mutually exclusive. \begin[type=autodoc:codeblock]{raw} \set[parameter=typesetter.orphanpenalty, value=250, makedefault=true] @@ -47,7 +47,7 @@ setting is localised to the content of the argument. In other words, this code: \set[parameter=typesetter.orphanpenalty, value=250]{\lorem} \end{raw} -will change the orphan penalty to 250, typeset 50 words of dummy text, and then +\noindent will change the orphan penalty to 250, typeset 50 words of dummy text, and then return the orphan penalty to its previous value. If you are working in Lua, you have two choices to work with. As with any @@ -66,13 +66,13 @@ arguments instead of named options: SILE.settings:set("typesetter.orphanpenalty", 250) \end{raw} -The 3rd and 4th optional arguments are for \em{makedefault} and \em{reset} +The third and fourth optional arguments are for \autodoc:parameter{makedefault} and \autodoc:parameter{reset} respectively. Now, let’s begin looking at what each of the built-in settings does, starting from the most obvious and moving towards the most subtle. -\section{Spacing Settings} +\section{Spacing settings} In our \code{\\note} example, we saw the setting \autodoc:setting{document.lskip}. This is a \em{glue} parameter which is added to the left side of every line. @@ -88,10 +88,10 @@ normal margins, such as to indent a pull-quote. They can also be negative, pulling the effective margin outside of the current frame. \begin{note} -\notehead{Glue} A \em{glue} parameter is slightly different from an ordinary dimensioned length. Glue basically means ‘space,’ but as well as signifying a length, +\notehead{Glue} A \autodoc:parameter{glue} parameter is slightly different from an ordinary dimensioned length. Glue basically means “space,” but as well as signifying a length, it also has two additional optional components: \em{stretch} and \em{shrink}, specified as \code{ plus minus }. The -first dimension is the basic length; the stretch is the maximum length that +first dimension is the basic length, the stretch is the maximum length that can be added to it, and the shrink is some length that can be taken away from it. For instance, \code{12pt plus 6pt minus 3pt} specifies a space that would ideally by 12 points, but can expand or contract from a minimum of 9 points to a maximum @@ -132,18 +132,18 @@ paragraphs.\par \set[parameter=document.spaceskip]% The indentation at the start of each paragraph is controlled by the setting \autodoc:setting{document.parindent}; this is a glue parameter, and by default it’s -set to 20pt with no stretch and shrink. Actually, the amount added to the +set to 20pt with no stretch and shrink. (In fact, the amount added to the start of the paragraph is \autodoc:setting{current.parindent}. After each paragraph, \autodoc:setting{current.parindent} is reset to the value of \autodoc:setting{document.parindent}. The -\autodoc:command{\noindent} command works by setting \autodoc:setting{current.parindent} to zero. +\autodoc:command{\noindent} command works by setting \autodoc:setting{current.parindent} to zero.) \medskip% \set[parameter=current.parindent,value=-20pt]% \set[parameter=document.lskip,value=20pt]% -How would you make a paragraph like this with a ‘hanging’ indentation? We’ve +How would you make a paragraph like this with a “hanging” indentation? We’ve set the \autodoc:setting{document.lskip} to 20 points, and the \autodoc:setting{current.parindent} to -\em{minus} 20 points. (In other words, we called: \autodoc:command{\set[parameter=document.lskip,value=20pt]} -and \autodoc:command{\set[parameter=current.parindent,value=-20pt]}.) +\em{minus} 20 points. In other words, we called: \autodoc:command{\set[parameter=document.lskip,value=20pt]} +and \autodoc:command{\set[parameter=current.parindent,value=-20pt]}. \medskip% \set[parameter=document.lskip,value=0pt]% @@ -257,7 +257,7 @@ Now we can finally complete our implementation of centering: \set[parameter=typesetter.parfillskip,value=0pt] And this is (more or less) how the \autodoc:environment{center} environment is defined in -the plain class: we make the margins able to expand but the spaces not able +the \code{plain} class: we make the margins able to expand but the spaces not able to expand; we turn off indenting at the start of the paragraph, and we turn off the filling glue at the end of the paragraph. \par @@ -322,14 +322,18 @@ engine in use. To get a list of the subshapers enabled in your build of Harfbuzz, run \code{sile --debug=versions} on any file: \begin[type=autodoc:codeblock]{raw} -% $ sile --debug=versions hello.sil +$ sile --debug=versions hello.sil + ... + Harfbuzz version: 2.4.0 + Shapers enabled: graphite2, ot, coretext, coretext_aat, fallback + ... \end{raw} -If I wanted to test out the OS X’s CoreText shaper instead of using +If I wanted to test out the macOS CoreText shaper instead of using Graphite and Harfbuzz’s own OpenType shaper, I could set: \begin[type=autodoc:codeblock]{raw} diff --git a/documentation/c08-language.sil b/documentation/c08-language.sil index 2f8195e76..111942d85 100644 --- a/documentation/c08-language.sil +++ b/documentation/c08-language.sil @@ -11,22 +11,21 @@ We want to make it easy for minority languages and scripts to implement their ow For SILE to know how to typeset text you will need to tell it what language your text is in! There are two ways to do this: -as part of the \code{\\font[language=...]} command as detailed in chapter 4, +as part of the \code{\\font[language=...]} command as detailed in Chapter 4, or by use of the \code{\\language[main=...]} command. Both of these expect an ISO639-1 language code such as \code{en} for English, \code{ar} for Arabic, and so on. -Selecting a language by either method loads up the \em{language support} file(s) for that language. +Selecting a language by either method loads up the \em{language support} files for that language. These in turn enable various localization and typesetting conventions. -Language support may include and combination of: +Language support may include: \begin{itemize} -\item{hyphenation patterns,} -\item{line breaking and justification schemes,} -\item{frame advance and writing direction,} -\item{spacing,} -\item{choice of glyphs within a font,} -\item{localization of programatically inserted strings,} -\item{and more…} +\item{hyphenation patterns} +\item{line breaking and justification schemes} +\item{frame advance and writing direction} +\item{spacing} +\item{choice of glyphs within a font} +\item{localization of programatically inserted strings} \end{itemize} For example, Sindhi and Urdu users will expect the Arabic letter \em{heh} (\font[family=LateefGR]{ه}) to combine with other letters in different ways to standard Arabic shaping. @@ -51,19 +50,19 @@ then in Urdu: \font[family=LateefGR,language=urd]{ههه}. \section{Direction} -SILE is written to be \em{direction-agnostic}, which means that it has -no fixed idea about which way text should flow on a page: Latin scripts +SILE is written to be \em{direction-agnostic,} which means that it has +no fixed idea about which way text should flow on a page. Latin scripts are generally written left-to-right with individual lines starting from the top of the page and advancing towards the bottom. Japanese can be written in the same way, but traditionally is typeset down the page with lines of text moving from the right of the page to the left. -To describe this, SILE uses the concept of a \em{writing direction}, -which denotes the way each individual line appears on the page —left +To describe this, SILE uses the concept of a \em{writing direction,} +which denotes the way each individual line appears on the page—left to right for Latin scripts, right to left for Arabic, Hebrew and so on, -top to bottom for traditional Japanese— and a \em{page advance direction}, -which denotes the way the lines “stack up”. Each of these directions can -take one of four values: \code{LTR}, \code{RTL}, \code{TTB} and \code{BTT}. +top to bottom for traditional Japanese—and a \em{page advance direction,} +which denotes the way the lines “stack up.” Each of these directions can +take one of four values: \code{LTR}, \code{RTL}, \code{TTB}, or \code{BTT}. A \em{direction specification} is made up of either a writing direction (\code{LTR} or \code{RTL}), in which case the page advance direction is understood to be \code{TTB}, or a writing direction and a page advance @@ -100,7 +99,7 @@ languages. The default hyphen character is “-”, which can be tweaked by the \code{\\font} parameter \code{hyphenchar}. It accepts a Unicode character or Unicode codepoint -in \code{[Uu]+} or Hexadecimal \code{0[Xx]} format – for instance +in \code{[Uu]+} or Hexadecimal \code{0[Xx]} format—for instance, \code{\\font[family=Rachana,language=ml,hyphenchar=U+200C]}. SILE comes with a special “language” called \code{und}, which has no hyphenation @@ -118,20 +117,20 @@ are available; if not, work through the resources at A small handful of strings may be programatically added to documents depending on language, context, and options. For example by default in English the \code{book} class will prepend “Chapter ” before chapter numbers output by the \code{\\chapter} command. -These localized strings are managed internally using the Fluent localization system. -See Project Fluent (\url{https://projectfluent.org}) for details on the data format and uses. +These localized strings are managed internally using the Fluent localization system.% +\footnote{See Project Fluent (\url{https://projectfluent.org}) for details on the data format and uses.} Some default localizations are provided for a handful of languages, but it is quite likely SILE will not (yet) have your language. Even if it does, it may not use the localization of your choice. All default localizations can be easily overridden and new locales can easily be added in your document or project. -Additionally the Fluent localization system is exposed and can be used for your localization purposes. +Additionally, the Fluent localization system is exposed and can be used for your localization purposes. To set a new value for a message (or messages), simply use the \code{\\ftl} command. The contents passed to the command will be parsed as new messages and loaded in the locale for the current document language. -Optionally messages may be loaded into a different locale with \code{\\ftl[locale=]}. +Optionally, messages may be loaded into a different locale with \code{\\ftl[locale=]}. You can also load messages from an external ftl file with \code{\\ftl[src=]}. -To output a localized message, pass the message id to the \code{\\fluent} command. +To output a localized message, pass the message ID to the \code{\\fluent} command. The current document languages determines the locale used, or a locale option may be passed. Fluent parameters may also be passed as options. @@ -159,7 +158,7 @@ SILE inserts word break opportunities after Ethiopic word spaces and full stops. Amharic can be typeset in two styles: with space surrounding punctuation or space after punctuation. You can set the setting \autodoc:setting[check=false]{languages.am.justification} to either \code{left} -or \code{centered} to control which style is used. The default is \code{left} +or \code{centered} to control which style is used. The default is \code{left}. \begin{autodoc:codeblock} \\font[family=Noto Sans Ethiopic,language=am] @@ -178,11 +177,13 @@ or \code{centered} to control which style is used. The default is \code{left} \define[command=eo]{\font[language=eo]{\process}} -Esperanto typesetting is quite straight forward, however one feature of the language is unique: +Esperanto typesetting is quite straight forward; however one feature of the language is unique: the requirement that \em{all} adjectives, including numerals, have the suffix “\eo{ª}”. This includes numbers standing on their own. -For example, “the 15th of March” is, in Esperanto, “\eo{la 15ª de marto}”. -As there is lack of agreement\footnote{Wikipedia prefers “\eo{15-a}” while most professional books and posters prefer “\eo{15ª}”, while some authors even write “\eo{15a}” as the underlying word is “\eo{dekkvina}”.} on how to typeset this, you have options: +For example, “the 15th of March” is, in Esperanto, “\eo{la 15ª de marto}.” +As there is lack of agreement% +\footnote{Wikipedia prefers “\eo{15-a}” while most professional books and posters prefer “\eo{15ª}.” Some authors even write “\eo{15a},” as the underlying word is “\eo{dekkvina}.”} +on how to typeset this, you have options: \autodoc:setting[check=false]{languages.eo.ordinal.raisedsuffix} when made true will use \eo{ª} (as in “\eo{Ĉapitro 1ª}”) while \autodoc:setting[check=false]{languages.eo.ordinal.hyphenbefore} will prepend a hyphen (as in “\eo{Ĉapitro 15-a}”). @@ -190,7 +191,7 @@ As there is lack of agreement\footnote{Wikipedia prefers “\eo{15-a}” while m In French typesetting, there is normally a non-breakable space between text and “high” punctuation (a thin fixed space before question marks, exclamation -marks, semicolons and an inter-word space before colons), and also spaces +marks, and semicolons, and an inter-word space before colons), and also spaces within “guillemets” (quotation marks). SILE will automatically apply the correct space. The size of these spaces is determined by \autodoc:setting[check=false]{languages.fr.thinspace}, @@ -200,10 +201,10 @@ correct space. The size of these spaces is determined by \subsection{Japanese / Chinese} SILE aims to conform with the W3G document “Requirements for Japanese Text Layout”\footnote{\url{https://www.w3.org/TR/jlreq/}} which describes the typographic conventions for Japanese (and also Chinese) text. -Breaking rules (kinzoku shori) and intercharacter spacing is fully supported on selecting the Japanese language. +Breaking rules \em{(kinzoku shori)} and intercharacter spacing is fully supported on selecting the Japanese language. The easiest way to set up the other elements of Japanese typesetting such as the \em{hanmen} grid and optional vertical typesetting support is by using the \code{jplain} or \code{jbook} classes. -For other languages with similar layout requriements more generic \code{tplain} and \code{tbook} classes are available that setup the layout elements without also setting the default language and font to Japanese specific values. -These are also good condidates to use as bases classes and extend for more language specific classes. +For other languages with similar layout requirements, more generic \code{tplain} and \code{tbook} classes are available that setup the layout elements without also setting the default language and font to Japanese specific values. +These are also good condidates to use as base classes and extend for more language-specific classes. \package-documentation{hanmenkyoshi} diff --git a/documentation/c09-concepts.sil b/documentation/c09-concepts.sil index 88f85b865..81023802f 100644 --- a/documentation/c09-concepts.sil +++ b/documentation/c09-concepts.sil @@ -11,29 +11,29 @@ you are a class designer, and will be able to follow the details of how SILE implements these commands and features; we will also explain how to interact with these components at the Lua level.} -\section{Boxes, Glue and Penalties} +\section{Boxes, glue, and penalties} -SILE’s job is, looking at it in very abstract terms, all about arranging +SILE’s job, looking at it in very abstract terms, is all about arranging little boxes on a page. Some of those boxes have letters in them, and those letters are such-and-such a number of points wide and such-and-such a number of points high; -some of the boxes are empty but are there just to take up space; when a -horizontal row of boxes has been decided (i.e. when a line break is determined) +some of the boxes are empty but are there just to take up space. +When a horizontal row of boxes has been decided (i.e., when a line break is determined) then the whole row of boxes is put into another box and the vertical list of boxes are then arranged to form a page. Conceptually, then, SILE knows about a few different basic components: -horizontal boxes (such as a letter); horizontal glue (the stretchable, shrinkable +horizontal boxes (such as a letter); horizontal glue (the stretchable or shrinkable space between words); vertical boxes (a line of text); vertical glue (the space between lines and paragraphs); and penalties (information about where and when not to break lines and pages).\footnote{Additionally there are three more types of box that SILE cares about: N-nodes, unshaped nodes, and discretionaries.} -The most immediately useful of these are horizontal and vertical glue. It -is possible to explicitly add horizontal and vertical glue into SILE‘s processing +The most immediately useful of these are horizontal and vertical glue. +Horizontal and vertical glue can be explicitly added into SILE‘s processing stream using the \code{\\glue} and \code{\\skip} commands. These take a -\code{width} and a \code{height} parameter respectively, both of which are -glue dimensions. So, for instance, the \code{\\smallskip} command is +\code{width} and a \code{height} parameter, respectively, both of which are +glue dimensions. For instance, the \code{\\smallskip} command is the equivalent of \code{\\skip[height=3pt plus 1pt minus 1pt]}; \code{\\thinspace} is defined as being \code{\\glue[width=0.16667em]}. @@ -41,7 +41,7 @@ Similarly, there is a \code{\\penalty} command for inserting penalty nodes; \code{\\break} is defined as \code{\\penalty[penalty=-10000]} and \code{\\nobreak} is \code{\\penalty[penalty=10000]}. -You can also create horizontal and vertical boxes from within SILE. One obvious +You can also create horizontal and vertical boxes from within SILE. One reason for doing so would be to explicitly avoid material being broken up by a page or line break; another reason for doing so would be that once you box some material up, you then know how wide or tall it is. The \code{\\hbox} and \code{\\vbox} @@ -67,7 +67,7 @@ local glue = SILE.nodefactory.glue({ width = l }) local vglue = SILE.nodefactory.vglue({ height = l }) \end{raw} -SILE’s typesetting is organised by the \code{SILE.typesetter} object; it +SILE’s typesetting is organised by the \code{SILE.typesetter} object. It maintains two queues of material that it is still working on: the node queue and the output queue. Material in these queues is content that has been parsed but not yet rendered to the canvas and can still be manipulated. The node queue @@ -78,28 +78,28 @@ that have not yet been broken up into lines. The output queue breaking happen when the typesetter moves between horizontal and vertical mode. As new content is parsed it is added to the node queue in as small chunks as -possible—chunks that must remain together no matter where they end up on -a line. For example this might include individual symbols, syllables, or objects such as +possible. These chunks must remain together no matter where they end up on +a line. This might include individual symbols, syllables, or objects such as images. As soon as new content which requires a vertical break is encountered, the node queue is processed to derive any missing shaping information about each node, then the sequence of node is broken up into lines. Once all the -"horizontal mode" nodes are broken into lines and those lines are added to the +“horizontal mode” nodes are broken into lines and those lines are added to the output queue, the other new vertical content can be processed. At any point you can force the current queue of horizontal content (the node queue) to be shaped into lines and added to the vertical output queue by calling the function -\code{SILE.typesetter:leaveHmode()}. This is a handy move for writing custom -functions, but it is a fairly low level control (i.e. it is unlikely to be -useful while writing a document). A related but higher level command, +\code{SILE.typesetter:leaveHmode()}. This is handy when for writing custom +functions, but it is a fairly low level control. (Tt is unlikely to be +useful while writing a document.) A related but higher level command, \code{\\par}, is more frequently used when writing a document and embedded in the content. The \code{\\par} command first calls \code{SILE.typesetter:leaveHmode()}, then inserts a vertical skip according to the \autodoc:setting{document.parskip} setting, then goes on to reset a number of -settings that are typically paragraph related such as hanging indents. +settings that are typically paragraph-related such as hanging indents. When writing a custom command, if you want to manually add a vertical space to -the output first ensure that the material in the current paragraph has been all +the output, first ensure that the material in the current paragraph has been all properly boxed-up and moved onto the output queue by calling -\code{SILE.typesetter:leaveHmode()}; then add your desired glue to the output +\code{SILE.typesetter:leaveHmode()}, then add your desired glue to the output queue. This is exactly what the \code{\\skip} and similar commands do. @@ -115,7 +115,7 @@ SILE.typesetter:pushVglue({ height = l }) Adding boxes yourself is a little more complicated, because boxes need to know how to display themselves on the page. To facilitate this, they normally store a \code{value} and an \code{outputYourself} member function. For instance, -the \code{image} package actually does something very simple; it adds a horizontal +the \code{image} package does something very simple: it adds a horizontal box to the node queue which knows the width and height of the image, the source, and instructions to the output engine to display the image: @@ -144,9 +144,9 @@ done with the \code{SILE.typesetter:pushPenalty(\{penalty = x\})} and S\lower[height=0.5ex]{I}L\kern[width=-.2em]\raise[height=0.6ex]{\font[features=+smcp]{e}}}} \define[command=SILEglue]{\font[family=Gentium Plus]{% S\lower[height=0.5ex]{I}L\glue[width=-.2em]\raise[height=0.6ex]{\font[features=+smcp]{e}}}} -\code{\\kern}’s are a type of \code{\\glue}. The difference between the two is -that, while a \code{\\glue} can be broken at the end of a line, a \code{\\kern} -can’t be. Hearkening back to our \SILEkern example from the \em{Macros and +\code{\\kern}’s are a type of \code{\\glue}, only different in that +while a \code{\\glue} can be broken at the end of a line, a \code{\\kern} +can’t. Hearkening back to our \SILEkern example from the \em{Macros and Commands} chapter, consider that example, repeated enough times to cause a linebreak, but with \code{\\glue}’s everywhere \code{\\kern}’s are used instead: @@ -155,23 +155,23 @@ instead: \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% -\SILEglue\SILEglue\color[color=#dd0000]{\SILEglue}\SILEglue\SILEglue% +\SILEglue\color[color=#dd0000]{\SILEglue}\SILEglue\SILEglue\SILEglue% \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% \line -The 27\sup{th} of the 60 \SILEglue’s, in \color[color=#dd0000]{red}, is broken +Note the \SILEglue in \color[color=#dd0000]{red} is broken between its ‘L’ and ‘\raise[height=0.6ex]{\font[family=Gentium Plus,features=+smcp]{e}}’. -Meanwhile, if we typeset the same line, except using \code{\\kern}’s as we had -originally instead… +Instead, if we typeset the same line using \code{\\kern}’s as we had +originally: \line \SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern% \SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern% \SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern% -\SILEkern\SILEkern\color[color=#dd0000]{\SILEkern}\SILEkern\SILEkern% +\SILEkern\color[color=#dd0000]{\SILEkern}\SILEkern\SILEkern\SILEkern% \SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern% \SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern% \SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern% @@ -207,14 +207,14 @@ and \code{\\frame} commands. There are very few situations in which you will actually want to do this, but if you can understand this, it will help you to understand how to define your own document classes. -For instance, in a couple of pages time we’re going to implement a two-column layout. +For instance, in a couple of page’s time, we’re going to implement a two-column layout. SILE uses a \em{constraint solver} system to declare its frames, which means that you can tell it how the frames relate to each other and it will compute where the frames should be physically placed on the page. Here is how we will go about it. We need to start with a page break, because SILE will not appreciate you changing the page layout after it’s started to -determine how to put text onto that page.\footnote{Of course you can use +determine how to put text onto that page.\footnote{You can use the \code{frametricks} package to get around this limitation—split the current frame and start fiddling around with the positions of the new frames that \code{frametricks} created for you.} How do we get to the start of a new @@ -223,7 +223,7 @@ vertical mode) only adds a penalty to the end of the output queue; page breaking is triggered when we leave horizontal mode, and the way to do that is \code{\\par}. So we start with \code{\\eject\\par} and then we will begin a \code{\\pagetemplate}. Within \code{\\pagetemplate} we need to tell SILE which frame to begin typesetting -onto. +onto: \begin[type=autodoc:codeblock]{raw} \eject\par @@ -245,11 +245,11 @@ except with three additional features: \begin{itemize} \item{You can refer to properties of other frames using the \code{top()}, \code{bottom()}, \code{left()}, \code{right()}, \code{height()} and - \code{width()} functions. These functions take a frame ID. SILE magically + \code{width()} functions. These functions take a frame ID. SILE pre-defines the frame \code{page} to allow you to access the dimensions of the whole page.} \item{You can use arithmetic functions: plus, minus, divide, multiply, and - parenthesis have their ordinary arithmetic meaning. To declare that frame + parentheses symbols have their ordinary arithmetic meaning. To declare that frame \code{b} should be half the height of frame \code{a} plus 5 millimeters, you can say \code{height=5mm + (height(b) / 2)}. However, as we will see later, it is usually better to structure your declarations to let SILE @@ -265,16 +265,16 @@ Next we declare the left and right column frames. The \code{book} class gives us some frames already, one of which, \code{content}, defines a typeblock with a decent size and positioning on the page. We will use the boundaries of this frame to declare our columns: the left -margin of the left column is the left margin of the typeblock; the right margin of +margin of the left column is the left margin of the typeblock, and the right margin of the right column is the right margin of the typeblock. But we also want a few other parameters to ensure that: \begin{itemize} \item{the gutter is placed between our two columns} -\item{the two columns have the same width (We don’t know what that width is, - but SILE will work it out for us.)} +\item{the two columns have the same width (we don’t know what that width is, + but SILE will work it out for us)} \item{after the left column is full, typesetting should move to the right - column.} + column} \end{itemize} \begin[type=autodoc:codeblock]{raw} diff --git a/documentation/c10-classdesign.sil b/documentation/c10-classdesign.sil index ee73abbc8..b6e62786f 100644 --- a/documentation/c10-classdesign.sil +++ b/documentation/c10-classdesign.sil @@ -6,7 +6,7 @@ to define one for an entire document. Document classes are Lua files, and live somewhere in the \code{classes/} subdirectory of either where your input file is located, your current working -directory or your SILE path (typically \code{/usr/local/share/sile}). We’re +directory, or your SILE path (typically \code{/usr/local/share/sile}). We’re going to create a simple class file which merely changes the size of the margins and the typeblock. We’ll call it \code{bringhurst.lua}, because it replicates the layout of the Hartley & Marks edition of Robert Bringhurst’s @@ -62,8 +62,7 @@ and the running headers live above the \code{content} frame. Normally, as in the \code{plain} class and anything inheriting from it, this would be enough to populate the pages’ frameset. -Instead the \code{book} class includes its own extension to the class with a callback init function. -We see that it loads the \code{masters} package and generates a master frameset using the above defined default frameset. +Instead the \code{book} class includes its own extension to the class with a callback \code{_init()} function which loads the \code{masters} package and generates a master frameset using the default frameset defined above. \begin[type=autodoc:codeblock]{raw} function book:_init (options) @@ -86,7 +85,7 @@ Next, we use the \code{twoside} package to mirror our right-page master into a l self:mirrorMaster("right", "left") \end{raw} -The book class also loads the table of contents package which sets up commands for sectioning, +The \code{book} class also loads the table of contents package which sets up commands for sectioning, and declares various things that need to be done at the start and end of each page. Since we will be inheriting from the book class, we will have all these definitions already available to us. @@ -104,9 +103,9 @@ return bringhurst Now we need to define our frame masters. -The LaTeX memoir class’ \em{A Few Notes On Book Design} tells us that Bringhurst’s book has a spine margin one thirteenth of the page width; -a top margin eight-fifths of the spine margin; -a front margin and bottom margin both sixteen-fifths of the spine margin. +The LaTeX memoir classes’ \em{A Few Notes On Book Design} tells us that Bringhurst’s book has a spine margin one thirteenth of the page width, +a top margin eight-fifths of the spine margin, +and a front margin and bottom margin both sixteen-fifths of the spine margin. We can define this in SILE terms like so: \begin[type=autodoc:codeblock]{raw} @@ -128,19 +127,19 @@ bringhurst.defaultFrameset = { } \end{raw} -Note that we’ve deliberately copied the frame definitions for the folio and footnote frames from the book class, -but if we had tried to reuse the runningHead frame definition it would have been too high -because the typeblock is higher on the page than the standard book class, +Note that we’ve deliberately copied the frame definitions for the folio and footnote frames from the \code{book} class, +but if we had tried to reuse the \code{runningHead} frame definition it would have been too high +because the typeblock is higher on the page than the standard \code{book} class, and the running heads are defined relative to them. So, we needed to change the definition the running header frame to bring them down a bit lower. If all we want to do in our new class is to create a different page shape, this is all we need. -The init function inherited from the book class will take care of setting these frames up with mirrored masters. +The \code{_init()} function inherited from the book class will take care of setting these frames up with mirrored masters. If we had wanted to load additional packages into our class as, say, the \code{bible} class does, -we would need to define our own init function and call our parent class’s init function as well. -For example to load the \code{infonode} package into our class, we could add this init function: +we would need to define our own \code{_init()} function and call our parent class’s \code{_init()} function as well. +For example to load the \code{infonode} package into our class, we could add this function: \begin[type=autodoc:codeblock]{raw} function bringhurst:_init(options) @@ -153,14 +152,14 @@ end Note that the official SILE classes have some extra tooling to handle legacy class models trying to inherit from them. You don’t need those deprecation shims in your own classes when following these examples. -\section{Defining Commands} +\section{Defining commands} -However, it’s usually the case that a class will want to do more than -just change the page shape; a class will typically want to do some other things +It’s usually the case that a class will want to do more than +just change the page shape. A class will typically want to do some other things as well: define additional commands, alter the output routine, store and investigate bits of state information, and so on. We’ll look briefly at some of the principles involved in those things here, and in the next -chapters will run through some worked examples. +chapters will run through some working examples. To define your own command at the Lua level, you use the \code{SILE.registerCommand} function. It takes three parameters: a command name, @@ -170,7 +169,7 @@ you need to take two parameters, \code{options} and \code{content} (of course you can name your parameters whatever you like, but these are the most common names). Both of these parameters are Lua tables. The \code{options} parameter contains the command’s parameters or XML attributes as a key-value table, -and the \code{content} is an abstract syntax tree reflecting the input being currently processed. +and the \code{content} parameter is an abstract syntax tree reflecting the input being currently processed. So in the case of \code{\\mycommand[size=12pt]\{Hello \\break world\}}, the first parameter will contain the table \code{\{size = "12pt"\}} and the second parameter will contain the table: @@ -190,11 +189,11 @@ the first parameter will contain the table \code{\{size = "12pt"\}} and the seco Most commands will find themselves doing something with the \code{options} and/or calling \break\code{SILE.process(content)} to recursively process the -argument. Here’s a very simple example; an XML \code{} tag may take +argument. Here’s a very simple example: an XML \code{} tag may take an XLink \code{xl:href} attribute\footnote{Yes, I know the document author might choose a different XML namespace to refer to XLink. Let’s keep things -simple.} We want to render \code{\goodbreak{}Hello} -as \examplefont{Hello (\code{http://...})}. So, first we need to render +simple.}. We want to render \code{\goodbreak{}Hello} +as \examplefont{Hello (\code{http://...})}. First we need to render the content, and then we need to do something with the attribute: \begin[type=autodoc:codeblock]{raw} @@ -219,13 +218,12 @@ functions to output text and call other commands. \note{If you do need to do something with a dimension, you can use \code{SILE.measurement()} to parse a basic length and \code{SILE.parseComplexFrameDimension} to parse a frame dimension, -and if necessary the \code{:tonumber()} method of dimensions turn them into numbers (in points).} +and, if necessary, the \code{:tonumber()} method of dimensions to turn them into numbers (in points).} -\section{Output Routines} +\section{Output routines} As well as defining frames and packages, -different classes also alter the way that SILE performs its output—what it should do at the start or end of a page, -for instance, which controls things like swapping between different master frames, +classes may also alter the way that SILE performs its output—for instance, what it should do at the start or end of a page, which controls things like swapping between different master frames, displaying page numbers, and so on. The key methods for defining the \em{output routine} are: @@ -243,17 +241,17 @@ Once again this is done in an object-oriented way, with derived classes overriding their superclass’ methods where necessary. Some packages may provide functions that need to be run as part of the class output routines. -One way packages can accomplish this is registering hook functions that get run at known locations in the provided classes. +One way packages can accomplish this is by registering hook functions that get run at known locations in the provided classes. Class authors may also provide their own hook locations for packages, or run any set of registered hooks in their own outputs. The other way is to export functions that get added to the class itself and can be run manually from the class. -For examples check out the \autodoc:package{tableofcontents} package for the hooks it sets, but also the \autodoc:command{\tocentry} command it registered that gets called manually in the \code{book} class. +For examples check out the \code{tableofcontents} package for the hooks it sets, but also the \autodoc:command{\tocentry} command it registers that gets called manually in the \code{book} class. Let’s demonstrate roughly how the \code{tableofcontents} package works. We’ll be using the \code{infonodes} package to collect the information about which pages contain table of content items. First, we set up our infonodes by creating a command that can be called by sectioning commands. -In other words, \code{\\chapter}, \code{\\section}, etc. should call \code{\\tocentry} to store the page reference for this section. +In other words, \code{\\chapter}, \code{\\section}, etc., should call \code{\\tocentry} to store the page reference for this section. \begin[type=autodoc:codeblock]{raw} SILE.registerCommand("tocentry", function (options, content) @@ -269,13 +267,13 @@ end) Infonodes work on a per-page basis, so if we want to save them throughout the whole document, at the end of each page we need to move them from the per-page table to our own -table. We also need to make sure we store their page numbers! +table. In order to be useful, we also need to make sure we store their page numbers. \note{SILE provides the \code{SILE.scratch} variable for you to store -global information in; you should use a portion of this table namespaced to +global information in. You should use a portion of this table namespaced to your class or package.} -So, here is a routine we can call at the end of each page to move the TOC nodes. +Here is a routine we can call at the end of each page to move the TOC nodes: \begin[type=autodoc:codeblock]{raw} SILE.scratch.tableofcontents = { } @@ -290,11 +288,11 @@ local moveNodes = function(self) end \end{raw} -We’re going to take the LaTeX approach of storing these items out as a +We’re going to take the LaTeX approach of storing these items as a separate file, then loading them back in again when typesetting the TOC. So at the end of the document, we serialize the \code{SILE.scratch.tableofcontents} table to disk. Here is a function to be called by the \code{finish} output -routine. +routine: \begin[type=autodoc:codeblock]{raw} local writeToc = function (self) @@ -303,7 +301,7 @@ local writeToc = function (self) end \end{raw} -And then the \code{\\tableofcontents} command reads that file if it is present, and typesets the TOC nodes appropriately: +Then the \code{\\tableofcontents} command reads that file if it is present, and typesets the TOC nodes appropriately: \begin[type=autodoc:codeblock]{raw} SILE.registerCommand("tableofcontents", function (options, content) @@ -322,7 +320,7 @@ end) And the job is done. Well, nearly. -The \code{tableofcontents} package now contains a couple of functions –\code{moveNodes} and \code{writeToc}– that need to be called at various points in the output routine of a class which uses this package. +The \code{tableofcontents} package now contains a couple of functions—\code{moveNodes} and \code{writeToc}—that need to be called at various points in the output routine of a class which uses this package. How do we do that? \section{Exports} @@ -357,5 +355,5 @@ In other words, after: \end{raw} \noindent{}any class which loads \code{tableofcontents} can call \code{self:writeToc()} and \code{self:moveTocNodes()} (note that we renamed this function when exporting it). -It is the class’s responsibility for calling these methods at the appropriate point into the output routine. +It is the class’s responsibility for calling these methods at the appropriate point in the output routine. \end{document} diff --git a/documentation/c11-xmlproc.sil b/documentation/c11-xmlproc.sil index 49385d1ba..16982a158 100644 --- a/documentation/c11-xmlproc.sil +++ b/documentation/c11-xmlproc.sil @@ -6,29 +6,29 @@ We’ll be looking at the DocBook processor that ships with SILE. DocBook is an XML format for structured technical documentation. DocBook itself doesn’t encode any presentation information about how its various tags should be rendered on a page, and so we shall have to make all the presentation decisions for ourself. -Since DocDook itself doesn’t specify anything about presentation such as papersize, you may need to supply values either on the command line or using a preamble. -When you use the \code{-c docbook} command line option to SILE, SILE will use the \em{docbook} class in spite of any document declaration. -In addition options such as paper size could be set with, e.g. \code{-O papersize=legal}. +Since DocDook itself doesn’t specify anything about presentation such as paper size, you may need to supply values either on the command line or using a preamble. +When you use the \code{-c docbook} command line option to SILE, SILE will use the \code{docbook} class in spite of any document declaration. +In addition, options such as paper size could be set; for example, \code{-O papersize=legal}. -The class initalization for DocBoox isn’t too fancy, it just loads up a couple packages that will get used later. - -Now we can start defining SILE commands to render XML elements. -Most of these are fairly straightforward so we will not dwell on them too much. -For instance, DocBook has tags like \code{}, \code{}, \code{} which should all be rendered in a monospaced typewriter font. -To make it easier to customize the class, we abstract out the font change into a single command: +The class initalization for DocBoox isn’t too fancy; it just loads up a couple packages that will get used later. \begin{note} -Much of the example code in this chapter is in SIL format using macros. -The actual docbook class currently uses Lua functions to specify these commands. +Much of the example code in this chapter is in SILE format using macros. +The actual \code{docbook} class currently uses Lua functions to specify these commands. The functionality is the same, but the Lua syntax is more flexible and recommended for most use cases. -The SILE define macros shown here can still be used in a preamble file if desired. +The SILE \code{\\define} macros shown here can still be used in a preamble file if desired. \end{note} +Now we can start defining SILE commands to render XML elements. +Most of these are fairly straightforward so we will not dwell on them too much. +For instance, DocBook has tags like \code{}, \code{}, and \code{} which should all be rendered in a monospaced typewriter font. +To make it easier to customize the class, we abstract out the font change into a single command: + \begin[type=autodoc:codeblock]{raw} \define[command=docbook-ttfont]{\font[family=Inconsolata,size=2ex]{\process}} \end{raw} -Now we can define our \code{} (etc.) tags: +Now we can define our tags for \code{} and other similar tags: \begin[type=autodoc:codeblock]{raw} \define[command=code]{\docbook-ttfont{\process}} @@ -41,20 +41,20 @@ Now we can define our \code{} (etc.) tags: If an end user wants things to look different, they can redefine the \code{docbook-ttfont} command and get a different font. -\section{Handling Titles} +\section{Handling titles} So much for simple tags. Things get interesting when there is a mismatch between the simple format of SILE macros and the complexity of DocBook markup. We have already seen an example of the \code{} tag where we also need to process XML attributes, so we will not repeat that here. Let’s look at another area of complexity: the apparently-simple \code{} tag. -The reason this is complex is that it occurs in different contexts, sometimes more than once within a context; it should often be rendered differently in different contexts. -So for instance \code{<article><title>...} will look different to \code{<section><title>...}. -Inside an \code{<example>} tag, the title will be prefixed by an example number; inside a \code{<bibliomixed>} bibliography entry the title should not be set off as a new block but should be part of the running text; and so on. +The reason this is complex is that it occurs in different contexts—sometimes more than once within a context—and it should often be rendered differently in different contexts. +For instance, \code{<article><title>...} will look different to \code{<section><title>...}. +Inside an \code{<example>} tag, the title will be prefixed by an example number; inside a \code{<bibliomixed>} bibliography entry, the title should not be set off as a new block but should be part of the running text, and so on. -What we will do to deal with this situation is provide a very simple definition of \code{<title>}, but when processing the containing elements of \code{<title>} (such as \code{<article>}, \code{<example>}), we will process the title ourselves. +What we will do to deal with this situation is provide a very simple definition of \code{<title>}, but when processing the containing elements of \code{<title>} (such as \code{<article>} and \code{<example>}), we will process the title ourselves. -For instance, let’s look at \code{<example>}, which has the added complexity of needing to keep track of an article number. +Let’s look at \code{<example>}, which has the added complexity of needing to keep track of an article number. \begin{verbatim} \line @@ -67,7 +67,7 @@ self:registerCommand("example", function(options,content) \end{verbatim} \code{\\docbook-line} is a command that we’ve defined in the \code{docbook.sil} macros file to draw a line across the width of the page to set off examples and so on. -\code{\\docbook-titling} is a command similarly defined in \code{docbook.sil} which sets the default font for titling and headers; once again, if people want to customize the look of the output we make it easier for them by giving them simple, compartmentalized commands to override. +\code{\\docbook-titling} is a command similarly defined in \code{docbook.sil} which sets the default font for titling and headers. Once again, if someone wants to customize the look of the output we make it easier for them by giving them simple, compartmentalized commands to override. So far so good, but how do we extract the \code{<title>} tag from the \code{content} abstract syntax tree? SILE does not provide XPath or CSS-style selectors to locate content form within the DOM tree;\footnote{Patches, as they say, are welcome.} instead there is a simple one-level function called \code{SILE.inputter:findInTree()} which looks for a particular tag or command name within the immediate children of the current tree: @@ -86,7 +86,7 @@ But we also need to ensure that the \code{<title>} tag doesn’t get processed a docbook.wipe(t) \end{verbatim} -\code{docbook.wipe} is a little helper function which nullifies all the content of a Lua table: +\code{docbook.wipe} is a little helper function which nullifies the content of a Lua table: \begin{verbatim} function docbook.wipe(tbl) @@ -106,15 +106,15 @@ Let’s finish off the \code{<example>} example by skipping a bit between the ti \line \end{verbatim} -Now it happens that the \code{<example>}, \code{<table>} and \code{<figure>} tags are pretty equivalent: they produce numbered titles and then go on to process their content. +It happens that the \code{<example>}, \code{<table>}, and \code{<figure>} tags are pretty equivalent: they produce numbered titles and then go on to process their content. So in reality we actually define an abstract \code{countedThing} method and define these commands in terms of that. \section{Sectioning} DocBook sectioning is a little different to the SILE \code{book} class. \code{<section>} tags can be nested; to start a subsection, you place another \code{<section>} tag inside the current \code{<section>}. -So in order to know what level we are currently on, we need a stack; we also need to keep track of what section number we are on at \em{each} level. -For instance: +So in order to know what level we are currently on, we need a stack. We also need to keep track of what section number we are on at \em{each} level. +For instance, with the expected section numbers and titles in XML comments: \begin{verbatim} <section><title>A : \examplefont{1. A} diff --git a/documentation/c12-tricks.sil b/documentation/c12-tricks.sil index 3647a04a2..155d0ff4a 100644 --- a/documentation/c12-tricks.sil +++ b/documentation/c12-tricks.sil @@ -3,10 +3,10 @@ We’ll conclude our tour of SILE by looking at some tricky situations which require further programming. -\section{Parallel Text} +\section{Parallel text} The example \url{https://sile-typesetter.org/examples/parallel.sil} -contains a rendering of chapter 1 of Matthew’s Gospel in English and Greek. +contains a rendering of Chapter 1 of Matthew’s Gospel in English and Greek. It uses the \code{diglot} class to align the two texts side-by-side. \code{diglot} provides the \code{\\left} and \code{\\right} commands to start entering text on the left column or the right column respectively, @@ -14,7 +14,7 @@ and the \code{\\sync} command to ensure that the two columns are in sync with ea It’s an instructive example of what can be done in a SILE class, so we will take it apart and see how it works. The key thing to note is that the SILE typesetter is an object (in the object-oriented programming sense). -Normally, it’s a singleton object—i.e. one typesetter is used for typesetting everything in a document. +Normally, it’s a singleton object—that is, one typesetter is used for typesetting everything in a document. But there’s no reason why we can’t have more than one. In fact, for typesetting parallel texts, the simplest way to do things is to have two typesetters, one for each column, and have them communicate with each other at various points in the operation. @@ -41,7 +41,7 @@ function diglot:_init (options) end \end{verbatim} -Now we create two new typesetters, one for each column, and we tell each one how to find the other: +Next we create two new typesetters, one for each column, and we tell each one how to find the other: \begin{verbatim} function diglot:_init (options) @@ -56,7 +56,7 @@ end Each column needs its own font, so we provide commands to store this information. The \code{\\leftfont} and \code{\\rightfont} macros simply store their options to be passed to the \code{\\font} command every time \code{\\left} and \code{\\right} are called. -(Because the fonts are controlled by global settings rather than being typesetter-specific.) +(This is because the fonts are controlled by global settings rather than being typesetter-specific.) \begin{verbatim} @@ -72,8 +72,8 @@ end \end{verbatim} Next come the commands for sending text to the appropriate typesetter. -The current typesetter object used by the system is stored in the variable \code{SILE.typesetter}; -many commands and packages call methods on this variable, +The current typesetter object used by the system is stored in the variable \code{SILE.typesetter}. +Many commands and packages call methods on this variable, so we need to ensure that this is set to the typesetter object that we want to use. We also want to turn off paragraph detection, as we will be handling the paragraphing manually using the \code{\\sync} command: @@ -99,9 +99,9 @@ In other words, if the left typesetter has gone further down the page than the r we need to insert some blank space onto the right typesetter’s output queue to get them back in sync, and vice versa. -SILE’s page builder has a method called \code{SILE.pagebuilder:collateVboxes} which bundles a bunch of vertical boxes into one; -we can use this to bundle up each typesetter’s output queue and measure the height of the combined vbox. -(Of course it’s possible to sum the heights of each box on the output queue by hand, +SILE’s page builder has a method called \code{SILE.pagebuilder:collateVboxes} which bundles a bunch of vertical boxes into one. +We can use this method to bundle up each typesetter’s output queue and measure the height of the combined vbox. +(Of course, it’s possible to sum the heights of each box on the output queue by hand, but this achieves the same goal a bit more cleanly.) \begin{verbatim} @@ -115,8 +115,8 @@ SILE.registerCommand("sync", function() end \end{verbatim} -Next we end each paragraph (we do this after adding the glue so that \code{parskips} -do not get in the way), and go back to handling paragraphing as normal: +Next we end each paragraph—after adding the glue so that \code{parskips} +do not get in the way—and go back to handling paragraphing as normal: \begin{verbatim} diglot.rightTypesetter:leaveHmode(); @@ -133,7 +133,7 @@ that each typesetter is linked to the appropriate frame: The default \code{newPage} routine will do this for one typesetter every time we open a new page, but it doesn’t know that we have another typesetter -object to set up as well; so we need to +object to set up as well. So we need to to make sure that, no matter which typesetter causes an new-page event, the other typesetter also gets correctly initialised: @@ -150,7 +150,7 @@ function diglot:newPage (self) end \end{verbatim} -And finally, when one typesetter causes an end-of-page event, we need to ensure +Finally, when one typesetter causes an end-of-page event, we need to ensure that the other typesetter is given the opportunity to output its queue to the page as well: @@ -161,10 +161,10 @@ function diglot:endPage = () end \end{verbatim} -Similarly for the end of the document, but in this case we will use the -emergency \code{chuck} method; whereas \code{leaveHmode} means “call the -page builder and see there’s enough material to build a page”, \code{chuck} -means “you must get rid of everything on your queue now.” We add some infinitely +At the end of the document, we will use the +emergency \code{chuck} method. Where \code{leaveHmode} means “call the +page builder and see there’s enough material to build a page,” \code{chuck} +means “you must get rid of everything on your queue \em{now.”} We add some infinitely tall glue to the other typesetter’s queue to help the process along: \begin{verbatim} @@ -175,12 +175,12 @@ function diglot:finish () end \end{verbatim} -And there you have it; a class which produces balanced parallel texts using two +And there you have it: a class which produces balanced parallel texts using two typesetters at once. \section{Sidenotes} -One SILE project needed two different kinds of sidenotes, margin notes and gutter +One SILE project needed two different kinds of sidenotes: margin notes and gutter notes. \line @@ -188,16 +188,16 @@ notes. \line Sidenotes can be seen as a simplified form of -parallel text. With a true parallel, neither the left or the right typesetter +parallel text. With a true parallel layout, neither the left or the right typesetter is “in charge”—either can fill up the page and then inform the other typesetter that they need to catch up. In the case of sidenotes, there’s a well-defined main flow of text, with annotations having to work around the pagination of the typeblock. -There are a variety of ways that we could implement these sidenotes; as it -happened, I chose a different strategy for the margin notes and the gutter notes. +There are a variety of ways that we could implement these sidenotes. As it +happened, we chose a different strategy for the margin notes and the gutter notes. Cross-references in the gutter could appear fairly frequently, and so needed to -“stack up” down the page—they need to be \em{at least} on a level with the verse +“stack up” down the page: they need to be \em{at least} on a level with the verse that they relate to, but could end up further down the page if there are a few cross-references close to each other. Markings in the margin, on the other hand, were guaranteed not to overlap. @@ -208,7 +208,7 @@ typeblock, actually outputs itself by marking the margin at the current vertical position in the typeblock. In the example above, there will be a special hbox just before the word “there” in the first line. -First we need to find the appropriate margin frame and, find its left boundary: +First we need to find the appropriate margin frame and find its left boundary: \begin{verbatim} \line @@ -249,13 +249,13 @@ symbol that we stored in the \code{hbox} variable. Finally we need to write the routine which outputs this hbox. Box output routines receive three parameters: the box itself, the current typesetter (which knows the frame it is typesetting into, and the frame -knows whereabouts it has got to), and a variable representing the stretchability +knows where it must go), and a variable representing the stretchability or shrinkability of the line. (We don’t need that for this example.) What our output routine should do is: save a copy of our horizontal position, so that we can restore it later as we carry on outputting other boxes; jump across to the left edge of the margin, which we computed previously; tell -the symbol that we’re carrying with us to output \em{itself}; and then jump +the symbol that we’re carrying with us to output \em{itself;} and then jump back to where we were: \begin{verbatim} @@ -276,7 +276,7 @@ which are closer to true sidenotes, we need to do something a bit more intellige We’ll take a similar approach to when we made the parallel texts, by employing a separate typesetter object. -As before we’ll create the object, and ensure that at the start of the document +As before, we’ll create the object, and ensure that at the start of the document and at the start of each page it is populated correctly with the appropriate frame: \begin{verbatim} @@ -308,8 +308,8 @@ end \end{verbatim} Now for the function which actually handles a cross-reference. As with the -parallels example, we start by totting up the height of the material processed -on the current page by both the main typesetter and the cross-reference typesetter. +parallels example, we start by totaling up the height of the material processed +on the current page by both the main typesetter and the cross-reference typesetter: \begin{verbatim} \line @@ -319,9 +319,9 @@ function discovery:typesetCrossReference (xref) local mainVbox = SILE.pagebuilder:collateVboxes(SILE.typesetter.state.outputQueue) \end{verbatim} -This deals with the material which has already been put into the output queue: in -other words, completed paragraphs. The problem here is that we do not want to -end a paragraph between two verses; if we are mid-paragraph while typesetting +This deals with the completed paragraphs which have already been put into the output queue. +The problem here is that we do not want to +end a paragraph between two verses: if we are mid-paragraph while typesetting a cross-reference, we need to work out what the height of the material \em{would have been} if we were to put it onto the output queue at this point. So, we take the \code{SILE.typesetter} object on a little excursion. @@ -331,10 +331,10 @@ First we take a copy of the current node queue, and then we call the typesetter its existing state for later. Since we have a new typesetter, its node queue is empty, and so we feed it the nodes that represent our paragraph so far. Then we tell the typesetter to leave horizontal mode, which will cause it to go away -and calculate line breaks, leading, paragraph height and so on. We box up its +and calculate line breaks, leading, paragraph height, and so on. We box up its output queue, and then return to where we were before. Now we have a box which represents what would happen if we set the current paragraph up to the point -that our cross-reference is inserted; the height of this box is the distance +that our cross-reference is inserted. The height of this box is the distance we need to add to \code{mainVbox} to get the vertical position of the cross-reference mark. @@ -351,10 +351,10 @@ mark. \note{The \code{1} argument to \code{leaveHmode} means “you may not create a new page here.”} -In most cases, the cross-reference typesetter hasn’t got as far down the page +In most cases, the cross-reference typesetter hasn’t gotten as far down the page as the body text typesetter, so we tell the cross-reference typesetter to shift itself down the page by the difference. Unlike the parallel example, where either typesetter -could tell the other to open up additional vertical space, in this case it’s OK if +could tell the other to open up additional vertical space, in this case it’s okay if the cross-reference appears a bit lower than the verse it refers to. \begin{verbatim} @@ -388,20 +388,20 @@ and then calling ordinary commands, rather than doing the settings and glue insertion “by hand.”} In the future it may make sense for there to be a standard \code{sidenotes} -package in SILE, but it has been instructive to see a couple of ‘non-standard’ +package in SILE, but it has been instructive to see a couple of “non-standard” examples to understand how the internals of SILE can be leveraged to create such a package. Your homework is to create one! -\section{SILE As A Library} +\section{SILE as a library} So far we’ve been assuming that you would want to run SILE as a processor for -an existing document. But what if you have a program which produces or munges +an existing document. But what if you have a program which produces or manipulates data, and you would like to produce PDFs from within your application? In that case, it may be easier and provide more flexibility to use SILE as a library. At \url{https://sile-typesetter.org/examples/byhand.lua}, you will find an example of a Lua script which produces a PDF from SILE. It’s actually fairly -simple to use SILE from within Lua; the difficult part is setting things up. +simple to use SILE from within Lua—the difficult part is setting things up. Here’s how to do it. \begin[type=autodoc:codeblock]{raw} @@ -421,7 +421,7 @@ typesetting, and then initialize the typesetter with this frame. This is all that SILE does to get itself ready to typeset. After this, all the usual API calls will work: \code{SILE.call}, -\code{SILE.typesetter:typeset} and so on. +\code{SILE.typesetter:typeset}, and so on. \begin{verbatim} SILE.typesetter:typeset(data) @@ -470,16 +470,16 @@ Running SILE with the \code{--debug \em{facility}} switch will turn on debugging and paragraphs into pages.} \item{\code{vboxes} provides even more information about page break decisions, showing you what vboxes were in SILE’s queue when considering the breaking.} -\item{\code{versions} gives a report on the versions of libraries and fonts in use; - please include this information when reporting bugs in SILE!} +\item{\code{versions} gives a report on the versions of libraries and fonts in use. + Please include this information when reporting bugs in SILE!} \item{Any package or other area of SILE’s operation may define their own debugging tags; the \code{insertions} package does this, as do the Japanese and Uyghur language support systems (\code{--debug uyghur}). Often the debug flag is the name of the package or the function.} \end{itemize} -Multiple facilities can be turned on by adding the flag multiple times or by separating them with commas: -\code{--debug typesetter,break} will turn on debugging information for the typesetter and line breaker. +Multiple facilities can be turned on by adding the flag multiple times or by separating them with commas. +For example, \code{--debug typesetter,break} will turn on debugging information for the typesetter and line breaker. From Lua, you can add entries to the \code{SILE.debugFlags} table to turn on debugging for a given facility. This can be useful for temporarily debugging a particular operation: diff --git a/documentation/developers.sil b/documentation/developers.sil index f5c3ffa26..316494a78 100644 --- a/documentation/developers.sil +++ b/documentation/developers.sil @@ -20,7 +20,7 @@ This book assumes that you’ve already read the SILE Book, and are now looking for further information about how SILE actually works. -The SILE cli itself is generated from the \code{sile.in} file and only handles some of the executable lifecycle stuff. +The SILE CLI itself is generated from the \code{sile.in} file and only handles some of the executable lifecycle stuff. The main core of SILE including most of the top level API is in \code{core/sile.lua}. This is also the file you would require in your own projects to get access to the SILE core as a library. It requires a lot of other things on its own, including some other file in \code{core}. @@ -34,7 +34,7 @@ However it is certainly possible to mix and match many alternatives in a single \chapter{From Input To PDF} Next we’ll give you a high-level overview of the process flow: what SILE does to get you from input to output. -\section{SILE Startup} +\section{SILE startup} \section{From input to AST} diff --git a/packages/autodoc/init.lua b/packages/autodoc/init.lua index 75f31a9c1..36b4154cc 100644 --- a/packages/autodoc/init.lua +++ b/packages/autodoc/init.lua @@ -329,26 +329,26 @@ For that purpose, it provides the \autodoc:command{\package-documentation{}, and sets the backgound of the current and all following pages to that color. -If setting only the current page background different from the default is desired, an extra parameter \autodoc:parameter{allpages=false} can be passed. +The package provides a \autodoc:command{\background} command which requires at least one parameter, \autodoc:parameter{color=}, and sets the background of the current and all following pages to that color. +If you want to set only the current page background different from the default, use the parameter \autodoc:parameter{allpages=false}. The color specification in the same as specified in the \autodoc:package{color} package. \background[color=#e9d8ba,allpages=false] diff --git a/packages/balanced-frames/init.lua b/packages/balanced-frames/init.lua index 4ac6e8fa9..97619d38a 100644 --- a/packages/balanced-frames/init.lua +++ b/packages/balanced-frames/init.lua @@ -95,7 +95,7 @@ end package.documentation = [[ \begin{document} This package attempts to ensure that the main content frames on a page are balanced; that is, that they have the same height. -In your frame definitions for the columns, you will need to ensure that they have the parameter \autodoc:parameter{balanced} set to a true value. +In your frame definitions for the columns, you will need to ensure that they have the parameter \autodoc:parameter{balanced} set to \code{true}. See the example in \code{tests/balanced.sil}. The current algorithm does not work particularly well, and a better solution to the column problem is being developed. diff --git a/packages/bibtex/init.lua b/packages/bibtex/init.lua index 0adf364df..584f97223 100644 --- a/packages/bibtex/init.lua +++ b/packages/bibtex/init.lua @@ -134,8 +134,8 @@ If you want to cite a particular page number, use \autodoc:command{\cite[page=22 To produce a full reference, use \autodoc:command{\reference{}}. -Currently, the only supported bibliography style is Chicago referencing, but other styles should be easy to implement if there is interest. -Check out \code{packages/bibtex/styles/chicago.lua} and adapt as necessary. +Currently, the only supported bibliography style is Chicago referencing, but other styles should be easy to implement. +Adapt \code{packages/bibtex/styles/chicago.lua} as necessary. \end{document} ]] diff --git a/packages/bidi/init.lua b/packages/bidi/init.lua index 8862b6c7b..b9eab110a 100644 --- a/packages/bidi/init.lua +++ b/packages/bidi/init.lua @@ -297,12 +297,12 @@ end package.documentation = [[ \begin{document} -Scripts like the Latin alphabet you are currently reading are normally written left to right; however, some scripts, such as Arabic and Hebrew, are written right to left. +Scripts like the Latin alphabet you are currently reading are normally written left to right (LTR); however, some scripts, such as Arabic and Hebrew, are written right to left (RTL). The \autodoc:package{bidi} package, which is loaded by default, provides SILE with the ability to correctly typeset right-to-left text and also documents which mix right-to-left and left-to-right typesetting. Because it is loaded by default, you can use both LTR and RTL text within a paragraph and SILE will ensure that the output characters appear in the correct order. The \autodoc:package{bidi} package provides two commands, \autodoc:command{\thisframeLTR} and \autodoc:command{\thisframeRTL}, which set the default text direction for the current frame. -That is, if you tell SILE that a frame is RTL, the text will start in the right margin and proceed leftward. +If you tell SILE that a frame is RTL, the text will start in the right margin and proceed leftward. It also provides the commands \autodoc:command{\bidi-off} and \autodoc:command{\bidi-on}, which allow you to trade off bidirectional support for a dubious increase in speed. \end{document} ]] diff --git a/packages/boustrophedon/init.lua b/packages/boustrophedon/init.lua index 7f041e4a2..ce81f8fd1 100644 --- a/packages/boustrophedon/init.lua +++ b/packages/boustrophedon/init.lua @@ -62,7 +62,7 @@ end package.documentation = [[ \begin{document} \use[module=packages.boustrophedon] -Partly designed to show off SILE’s extensibility, and partly designed for real use by classicists, the \autodoc:package{boustrophedon} package allows you to typeset ancient Greek texts in the ‘ox-turning’ layout—the first line is written left to right as normal, but the next is set right to left, then left to right, and so on. +Partly designed to show off SILE’s extensibility, and partly designed for real use by classicists, the \autodoc:package{boustrophedon} package allows you to typeset ancient Greek texts in the “ox-turning” layout: the first line is written left to right as normal, but the next is set right to left, then left to right, and so on. To use it, you will need to set the font’s language to ancient Greek (\code{grc}) and wrap text in a \autodoc:environment{boustrophedon} environment: \set[parameter=document.parindent,value=0]{\par diff --git a/packages/break-firstfit/init.lua b/packages/break-firstfit/init.lua index 30e02ab22..f40b93767 100644 --- a/packages/break-firstfit/init.lua +++ b/packages/break-firstfit/init.lua @@ -14,12 +14,12 @@ end package.documentation = [[ \begin{document} -SILE’s normal page breaking algorithm is based on the Knuth-Plass “best-fit”method, which tests a variety of possible paragraph constructions before deciding on the visually optimal one. +SILE’s normal page breaking algorithm is based on the Knuth-Plass “best-fit” method, which tests a variety of possible paragraph constructions before deciding on the visually optimal one. That guarantees great results for texts which require full justification, but some languages don’t need that degree of complexity. In particular, Japanese is traditionally typeset on a grid system with characters being essentially monospaced. -You don’t need to do anything clever to break that into lines: just stop when you get to the end of the line and start a new one (the “first-fit” method). -This package implements the first-fit technique. -It’s currently designed to be used by other packages so it doesn’t currently provide any user-facing commands. +You don’t need to do anything clever to break that into lines: just stop when you get to the end of the line and start a new one. +This package implements this “first-fit” method. +It’s designed to be used by other packages so it doesn’t currently provide any user-facing commands. \end{document} ]] diff --git a/packages/chordmode/init.lua b/packages/chordmode/init.lua index 8dae36b5a..541ceab83 100644 --- a/packages/chordmode/init.lua +++ b/packages/chordmode/init.lua @@ -142,7 +142,7 @@ into: \par \end{examplefont} -The chords can be styled by redefining the \autodoc:command{\chordmode:chordfont} command, and the offset between the chord name and text set with the \autodoc:setting{chordmode.offset} setting. +The chords can be styled by redefining the \autodoc:command{\chordmode:chordfont} command, and the offset between the chord name and text adjusted with the \autodoc:setting{chordmode.offset} setting. \end{document} ]] diff --git a/packages/color/init.lua b/packages/color/init.lua index 23ef4229d..2ee86b494 100644 --- a/packages/color/init.lua +++ b/packages/color/init.lua @@ -25,7 +25,7 @@ The package provides a \autodoc:command{\color} command which takes one paramete The color specification is one of the following: \begin{itemize} -\item{A RGB color in \code{#xxx} or \code{#xxxxxx} format, where \code{x} represents a hexadecimal digit, as often seen in HTML/CSS (\code{#000} is black, \code{#fff} is white, \code{#f00} is red and so on);} +\item{A RGB color in \code{#xxx} or \code{#xxxxxx} format, where \code{x} represents a hexadecimal digit, as often seen in HTML/CSS (\code{#000} is black, \code{#fff} is white, \code{#f00} is red, and so on);} \item{A RGB color as a series of three numeric values between 0 and 255 (e.g. \code{0 0 139} is a dark blue) or as three percentages;} \item{A CMYK color as a series of four numeric values between 0 and 255 or as four percentages;} \item{A grayscale color as a numeric value between 0 and 255;} @@ -34,7 +34,8 @@ The color specification is one of the following: So, for example, \color[color=red]{this text is typeset with \autodoc:command{\color[color=red]{…}}}. -Here is a rule typeset with \autodoc:command{\color[color=#22dd33]}: \color[color=#ffdd33]{\hrule[width=120pt,height=0.5pt]} \end{document} +Here is a rule typeset with \autodoc:command{\color[color=#22dd33]}: \color[color=#22dd33]{\hrule[width=120pt,height=0.5pt]} +\end{document} ]] return package diff --git a/packages/converters/init.lua b/packages/converters/init.lua index 0d9097bb5..ecc4b68aa 100644 --- a/packages/converters/init.lua +++ b/packages/converters/init.lua @@ -111,13 +111,14 @@ The \autodoc:package{converters} package allows you to register additional handl That sounds a bit abstract, so it’s best explained by example. Suppose you have a GIF image that you would like to include in your document. You read the documentation for the \autodoc:package{image} package and you discover that sadly GIF images are not supported. -What \autodoc:package{converters} does is allow you to teach SILE how to get the GIF format into something that \em{is} supported. -We can use the ImageMagick toolkit to turn a GIF into a JPG, and JPGs are supported. +The \autodoc:package{converters} package allows you to teach SILE how to get the GIF format into something that \em{is} supported. +We can use the ImageMagick toolkit to turn a GIF into a JPEG, and JPEGs are supported directly by SILE. We do this by registering a converter with the \autodoc:command{\converters:register} command: \begin[type=autodoc:codeblock]{raw} \use[module=packages.converters] + \converters:register[from=.gif,to=.jpg,command=convert $SOURCE $TARGET] \end{raw} @@ -129,7 +130,7 @@ And now it just magically works: This will execute the command \code{convert hello.gif hello.jpg} and include the converted \code{hello.jpg} file. -This trick also works for text file: +This trick also works for text files: \begin[type=autodoc:codeblock]{raw} \converters:register[from=.md, to=.sil, command=pandoc -o $TARGET $SOURCE] diff --git a/packages/counters/init.lua b/packages/counters/init.lua index a146f1c94..cbb6236c2 100644 --- a/packages/counters/init.lua +++ b/packages/counters/init.lua @@ -202,24 +202,24 @@ package.documentation = [[ \begin{document} Various parts of SILE such as the \autodoc:package{footnotes} package and the sectioning commands keep a counter of things going on: the current footnote number, the chapter number, and so on. -The counters package allows you to set up, increment and typeset named counters. +The counters package allows you to set up, increment, and typeset named counters. It provides the following commands: \begin{itemize} -\item{\autodoc:command{\set-counter[id=, value=]} — sets the counter with the specified name to the given value. The command takes an optional \autodoc:parameter{display=} parameter to set the display type of the counter (see below).} -\item{\autodoc:command{\increment-counter[id=]} — increments the counter by one. The command creates the counter if it does not exist and also accepts setting the display type.} -\item{\autodoc:command{\show-counter[id=]} — typesets the value of the counter according to the counter’s declared display type.} +\item{\autodoc:command{\set-counter[id=, value=]}: Sets the counter with the specified name to the given value. The command takes an optional \autodoc:parameter{display=} parameter to set the display type of the counter (see below).} +\item{\autodoc:command{\increment-counter[id=]}: Increments the counter by one. The command creates the counter if it does not exist and also accepts setting the display type.} +\item{\autodoc:command{\show-counter[id=]}: Typesets the value of the counter according to the counter’s declared display type.} \end{itemize} The available built-in display types are: \begin{itemize} -\item{\code{arabic}, the default;} -\item{\code{alpha}, for lower-case alphabetic counting;} -\item{\code{Alpha}, for upper-case alphabetic counting;} -\item{\code{roman}, for lower-case Roman numerals; and,} -\item{\code{ROMAN} for upper-case Roman numerals.} +\item{\code{arabic}, the default} +\item{\code{alpha}, for lower-case alphabetic counting} +\item{\code{Alpha}, for upper-case alphabetic counting} +\item{\code{roman}, for lower-case Roman numerals} +\item{\code{ROMAN} for upper-case Roman numerals} \end{itemize} The ICU library also provides ways of formatting numbers in global (non-Latin) scripts. @@ -239,26 +239,28 @@ So, for example, the following SILE code: produces: \fullrule -\examplefont{2 +\examplefont{ +\noindent{}2 \noindent{}iii} +\par \fullrule The package also provides multi-level (hierarchical) counters, of the kind used in sectioning commands: \begin{itemize} -\item{\autodoc:command{\set-multilevel-counter[id=, level=, value=]} -— sets the multi-level counter with the specified name to the given value at the given level. +\item{\autodoc:command{\set-multilevel-counter[id=, level=, value=]}: +Sets the multi-level counter with the specified name to the given value at the given level. The command also takes an optional \autodoc:parameter{display=}, also acting at the given level.} -\item{\autodoc:command{\increment-multilevel-counter[id=]} -— increments the counter by one at its current (deepest) level. +\item{\autodoc:command{\increment-multilevel-counter[id=]}: +Increments the counter by one at its current (deepest) level. The command creates the counter if it does not exist. If given the \autodoc:parameter{level=} parameter, the command increments that level, -clearing any lower level (and filling previous levels with zeros, if they weren’t proprely set). +clearing any lower level (and filling previous levels with zeros, if they weren’t properly set). It also accepts setting the display type at the target level.} -\item{\autodoc:command{\show-multilevel-counter[id=]} -— typesets the value of the multi-level counter according to the counter’s declared display types +\item{\autodoc:command{\show-multilevel-counter[id=]}: +Typesets the value of the multi-level counter according to the counter’s declared display types at each level. By default, all levels are output; option \autodoc:parameter{level=} may be used to display the counter up to a given level. Option \autodoc:parameter{noleadingzeros=true} skips any leading zero (which may happen if a counter is at some level, without previous levels diff --git a/packages/cropmarks/init.lua b/packages/cropmarks/init.lua index c1737bc07..3bd3c3a56 100644 --- a/packages/cropmarks/init.lua +++ b/packages/cropmarks/init.lua @@ -99,7 +99,7 @@ end package.documentation = [[ \begin{document} When preparing a document for printing, you may be asked by the printer to add crop marks. -This means that you need to output the document on a slightly larger page size than your target paper and add printers crop marks to show where the paper should be trimmed down to the correct size. +This means that you need to output the document on a slightly larger page size than your target paper and add printer’s crop marks to show where the paper should be trimmed down to the correct size. (This is to ensure that pages where the content “bleeds” off the side of the page are correctly cut.) This package provides the \autodoc:command{\crop:setup} command which should be run early in your document file. diff --git a/packages/date/init.lua b/packages/date/init.lua index 990253ffa..df819499d 100644 --- a/packages/date/init.lua +++ b/packages/date/init.lua @@ -32,9 +32,9 @@ end package.documentation = [[ \begin{document} -The \autodoc:package{date} package provides the \autodoc:command{\date} command, which simply outputs the date using the system’s date function. -You can customize the format by passing the \autodoc:parameter{format} parameter, following the formatting codes in the Lua manual. -(\url{https://www.lua.org/pil/22.1.html}) +The \autodoc:package{date} package provides the \autodoc:command{\date} command, which simply outputs the current date using the system’s date function. +You can customize the format by passing the \autodoc:parameter{format} parameter, following the formatting codes in the Lua manual +(\url{https://www.lua.org/pil/22.1.html}). \end{document} ]] diff --git a/packages/debug/init.lua b/packages/debug/init.lua index 92635a22a..173ba2458 100644 --- a/packages/debug/init.lua +++ b/packages/debug/init.lua @@ -19,7 +19,7 @@ end package.documentation = [[ \begin{document} -This package provides two commands: \autodoc:command{\debug}, which turns on and off SILE’s internal debugging flags (similar to using \code{--debug=...} on the command line); and \autodoc:command{\disable-pushback} which is used by SILE’s developers to turn off the typesetter’s pushback routine, because we don’t really trust it very much. +This package provides two commands: \autodoc:command{\debug}, which turns on and off SILE’s internal debugging flags (similar to using \code{--debug=...} on the command line), and \autodoc:command{\disable-pushback} which is used by SILE’s developers to turn off the typesetter’s pushback routine, because we don’t really trust it very much. \end{document} ]] diff --git a/packages/dropcaps/init.lua b/packages/dropcaps/init.lua index 0697ac3a6..81106d9f2 100644 --- a/packages/dropcaps/init.lua +++ b/packages/dropcaps/init.lua @@ -80,22 +80,22 @@ end package.documentation = [[ \begin{document} -The \autodoc:package{dropcaps} package allows you to format paragraphs with an 'initial capital' (also commonly referred as a 'drop cap'), typically one large capital letter used as a decorative element at the beginning of a paragraph. +The \autodoc:package{dropcaps} package allows you to format paragraphs with an “initial capital” (also commonly referred as a “drop cap”), typically one large capital letter used as a decorative element at the beginning of a paragraph. It provides the \autodoc:command{\dropcap} command. The content passed will be the initial character(s). -The primary option is \autodoc:parameter{lines}, an integer specifying the number of lines to span (defaults to 3). -The scale of can be adjusted relative to the first line using the \autodoc:parameter{scale} option (defaults to 1.0). -The \autodoc:parameter{join} is a boolean for whether to join the dropcap to the first line (defaults to false). -If \autodoc:parameter{join} is true, the value of the \autodoc:parameter{standoff} option (defaults to 1spc) is applied to all but the first line. -Optionally \autodoc:parameter{color} can be passed to change the typeface color, sometimes useful to offset the apparent weight of a large glyph. +The primary option is \autodoc:parameter{lines}, an integer specifying the number of lines to span (defaults to \code{3}). +The scale of the characters can be adjusted relative to the first line using the \autodoc:parameter{scale} option (defaults to \code{1.0}). +The \autodoc:parameter{join} parameter is a boolean for whether to join the dropcap to the first line (defaults to \code{false}). +If \autodoc:parameter{join} is \code{true}, the value of the \autodoc:parameter{standoff} option (defaults to \code{1spc}) is applied to all but the first line. +Optionally \autodoc:parameter{color} can be passed to change the typeface color, which is sometimes useful to offset the apparent weight of a large glyph. To tweak the position of the dropcap, measurements may be passed to the \autodoc:parameter{raise} and \autodoc:parameter{shift} options. Other options passed to \autodoc:command{\dropcap} will be passed through to \autodoc:command{\font} when drawing the initial letter(s). This may be useful for passing OpenType options or other font preferences. \begin{note} One caveat is that the size of the initials is calculated using the default linespacing mechanism. -If you are using an alternative method from the linespacing package, you might see strange results. +If you are using an alternative method from the \autodoc:package{linespacing} package, you might see strange results. Set the \autodoc:setting{document.baselineskip} to approximate your effective leading value for best results. If that doesn't work set the size manually. Using \code{SILE.setCommandDefaults()} can be helpful for so you don't have to set the size every time. diff --git a/packages/features/init.lua b/packages/features/init.lua index 47099b0b0..6e53f2a2c 100644 --- a/packages/features/init.lua +++ b/packages/features/init.lua @@ -226,7 +226,7 @@ The \autodoc:package{features} package provides an interface to selecting the fe The features available will be specific to the font file; some fonts come with documentation explaining their supported features. Discussion of OpenType features is beyond the scope of this manual. -These features can be turned on and off by passing ‘raw’ feature names to the \autodoc:command{\font} command like so: +These features can be turned on and off by passing “raw” feature names to the \autodoc:command{\font} command like so: \begin[type=autodoc:codeblock]{raw} \font[features="+dlig,+hlig"]{...} % turn on discretionary and historic ligatures diff --git a/packages/folio/init.lua b/packages/folio/init.lua index 98e75ae59..4356b09c0 100644 --- a/packages/folio/init.lua +++ b/packages/folio/init.lua @@ -76,7 +76,7 @@ end package.documentation= [[ \begin{document} -The \autodoc:package{folio} package (which is automatically loaded by the plain class, and therefore by nearly every SILE class) controls the output of folios—the old-time typesetter word for page numbers. +The \autodoc:package{folio} package (which is automatically loaded by the \code{plain} class, and therefore by nearly every SILE class) controls the output of folios—the old-time typesetter word for page numbers. It provides four commands to users: @@ -95,7 +95,7 @@ If, for instance, you want to set page numbers in a different font you can redef If you want to put page numbers on the left side of even pages and the right side of odd pages, there are a couple of ways you can do that. The complicated way is to define a command in Lua which inspects the page number and then sets the number ragged left or ragged right appropriately. -The easy way is just to put your folio frame where you want it on the master page... +The easy way is just to put your folio frame where you want it on the master page. \end{document} ]] diff --git a/packages/font-fallback/init.lua b/packages/font-fallback/init.lua index e973f40f4..acf1acfe7 100644 --- a/packages/font-fallback/init.lua +++ b/packages/font-fallback/init.lua @@ -42,7 +42,7 @@ end package.documentation = [[ \begin{document} What happens when SILE is asked to typeset a character which is not in the current font? -For instance, we are currently using the “Gentium” font, which covers a wide range of European scripts; however, it doesn’t contain any Japanese character. +For instance, we are currently using the Gentium font, which covers a wide range of European scripts; however, it doesn’t contain any Japanese characters. So what if I ask SILE to typeset \code{abc \font[family=Noto Sans CJK JP]{あ}}? Many applications will find another font on the system containing the appropriate character and use that font instead. diff --git a/packages/footnotes/init.lua b/packages/footnotes/init.lua index f15e8610e..931d694b7 100644 --- a/packages/footnotes/init.lua +++ b/packages/footnotes/init.lua @@ -110,8 +110,8 @@ package.documentation = [[ \begin{document} We’ve seen that the \code{book} class allows you to add footnotes to text with the \autodoc:command{\footnote} command. This functionality exists in the class because the class loads the \autodoc:package{footnotes} package. -The \code{book} class loads up the \autodoc:package{insertions} package and tells it which frame should recieve the footnotes that are typeset. -After commands provided by the \autodoc:package{footnotes} package take care of formatting the footnotes. +The \code{book} class loads the \autodoc:package{insertions} package and tells it which frame should receive the footnotes that are typeset. +Other commands provided by the \autodoc:package{footnotes} package take care of formatting the footnotes. \end{document} ]] diff --git a/packages/frametricks/init.lua b/packages/frametricks/init.lua index 6dce1aa3b..a2fa11e3b 100644 --- a/packages/frametricks/init.lua +++ b/packages/frametricks/init.lua @@ -260,8 +260,8 @@ We just issued a \autodoc:command{\breakframevertical} command at the start of t As you can see, the current frame is called \code{\script{SILE.typesetter:typeset(SILE.typesetter.frame.id)}} and now begins at the start of the paragraph. Similarly, the \autodoc:command{\breakframehorizontal} command breaks the frame in two into a left and a right frame. -The command takes an optional argument \autodoc:parameter{offset=}, specifying where on the line the frame should be split. -If it is not supplied, the frame is split at the current position in the line. +The command takes an optional parameter \autodoc:parameter{offset=}, specifying where on the line the frame should be split. +If \autodoc:parameter{offset} is not supplied, the frame is split at the current position in the line. The command \autodoc:command{\shiftframeedge} allows you to reposition the current frame left or right. It takes \autodoc:parameter{left} and/or \autodoc:parameter{right} parameters, which can be positive or negative dimensions. @@ -269,15 +269,16 @@ It should only be used at the top of a frame, as it reinitializes the typesetter Combining all of these commands, the \autodoc:command{\float} command breaks the current frame, creates a small frame to hold a floating object, flows text into the surrounding frame, and then, once text has descended past the floating object, moves the frame back into place again. It takes two optional parameters, \autodoc:parameter{bottomboundary=} and/or \autodoc:parameter{rightboundary=}, which open up additional space around the frame. -At the start of this paragraph, I issued the command -\begin[type=autodoc:codeblock]{raw} -\float[bottomboundary=5pt]{\font[size=60pt]{C}}. -\end{raw} +% At the start of this paragraph, I issued the command +% +% \begin[type=autodoc:codeblock]{raw} +% \float[bottomboundary=5pt]{\font[size=60pt]{C}} +% \end{raw} To reiterate: we started playing around with frames like this in the early days of SILE and they have not really proved a good solution to the things we wanted to do with them. They’re great for arranging where content should live on the page, but messing about with them dynamically seems to create more problems than it solves. -There’s probably a reason why InDesign and similar applications handle floats, drop caps, tables and so on inside the context of a content frame rather than by messing with the frames themselves. +There’s probably a reason why InDesign and similar applications handle floats, drop caps, tables, and so on inside the context of a content frame rather than by messing with the frames themselves. If you feel tempted to play with \autodoc:package{frametricks}, there’s almost always a better way to achieve what you want without it. \end{document} ]] diff --git a/packages/grid/init.lua b/packages/grid/init.lua index 81864c314..9df14d28c 100644 --- a/packages/grid/init.lua +++ b/packages/grid/init.lua @@ -76,23 +76,23 @@ In normal typesetting, SILE determines the spacing between lines of type accordi \begin{itemize} \item{SILE tries to insert space between two successive lines so that their baselines are separated by a fixed distance called the \code{baselineskip}.} \item{If this first rule would mean that the bottom and the top of the lines are less than two points apart, then they are forced to be two points apart. - (This distance is configurable, and called the \code{lineskip}).} + (This distance is configurable, and called the \code{lineskip}.)} \end{itemize} -The second rule is designed to avoid the situation where the first line has a long descender (letters such as g, q, j, p, etc.) which abuts a high ascender on the second line. (k, l, capitals, etc.) +The second rule is designed to avoid the situation where the first line has a long descender (letters such as g, q, j, p, etc.) which abuts a high ascender on the second line (k, l, capitals, etc.). -In addition, the \code{baselineskip} contains a certain amount of ‘stretch’, so that the lines can expand if this would help with producing a page break at an optimal location, and similarly spacing between paragraphs can stretch or shrink. +In addition, the \code{baselineskip} contains a certain amount of “stretch,” so that the lines can expand if this would help with producing a page break at an optimal location, and similarly spacing between paragraphs can stretch or shrink. The combination of all of these rules means that a line may begin at practically any point on the page. An alternative way of typesetting is to require that lines begin at fixed points on a regular grid. -Some people prefer the ‘color’ of pages produced by grid typesetting, and the method is often used when typesetting on very thin paper as lining up the lines of type on both sides of a page ensures that ink does not bleed through from the back to the front. +Some people prefer the “color” of pages produced by grid typesetting, and the method is often used when typesetting on very thin paper, as lining up the lines of type on both sides of a page ensures that ink does not bleed through from the back to the front. Compare the following examples: on the left, the lines are guaranteed to fall in the same places on the recto (front) and the verso (back) of the paper; on the right, no such guarantee is made. \img[src=documentation/grid-1.png,height=130] \img[src=documentation/grid-2.png,height=130] -The \autodoc:package{grid} package alters the way that the SILE’s typesetter operates so that the two rules above do not apply; lines are always aligned on a fixed grid, and spaces between paragraphs etc. are adjusted to conform to the grid. +The \autodoc:package{grid} package alters the operation of SILE’s typesetter so that the two rules above do not apply; lines are always aligned on a fixed grid, and spaces between paragraphs, etc., are adjusted to conform to the grid. Loading the package adds two new commands to SILE: \autodoc:command{\grid[spacing=]} and \autodoc:command{\no-grid}. The first turns on grid typesetting for the remainder of the document; the second turns it off again. diff --git a/packages/gutenberg/init.lua b/packages/gutenberg/init.lua index 3e39716e4..a7afb66ef 100644 --- a/packages/gutenberg/init.lua +++ b/packages/gutenberg/init.lua @@ -27,8 +27,8 @@ end package.documentation = [[ \begin{document} -One of the reasons why Johann Gutenberg’s 42 line Bible is considered a masterpiece of early printing is due to the quality of justification of every line. -To achieve perfect justification color, Gutenberg used a number of ligatures, abbreviations, substitutions and so on. +Johann Gutenberg’s 42-line Bible is considered a masterpiece of early printing in part due to the quality of justification of every line. +To achieve perfect justification color, Gutenberg used a number of ligatures, abbreviations, substitutions, and so on. As an experiment in extending SILE’s justification engine, the \code{gutenberg} package allows SILE to choose between a number of different options for a particular piece of text, depending on what would improve the line fitting. For instance, issuing the command \autodoc:command{\alternative{\{and\}\{&\}}} would insert either the text \examplefont{and} or an ampersand, depending on what best fits the current line. diff --git a/packages/hanmenkyoshi/init.lua b/packages/hanmenkyoshi/init.lua index d94faaa95..cf21bdb08 100644 --- a/packages/hanmenkyoshi/init.lua +++ b/packages/hanmenkyoshi/init.lua @@ -92,9 +92,8 @@ end package.documentation = [[ \begin{document} -Japanese documents are traditionally typeset on a grid layout called a \code{hanmen}, with each character essentially monospaced inside the grid. -(It’s like writing on graph paper.) -The \autodoc:package{hanmenkyoshi} package provides tools to Japanese class designers for creating hanmen frames with correctly spaced grids. +Japanese documents are traditionally typeset on a grid layout called a \em{hanmen}, with each character essentially monospaced inside the grid (like writing on graph paper). +The \autodoc:package{hanmenkyoshi} package provides tools to Japanese class designers for creating \em{hanmen} frames with correctly spaced grids. It also provides the \autodoc:command{\show-hanmen} command for debugging the grid. The name \em{hanmenkyoshi} is a terrible pun. diff --git a/packages/image/init.lua b/packages/image/init.lua index ed55fcbf9..e81e6acff 100644 --- a/packages/image/init.lua +++ b/packages/image/init.lua @@ -40,16 +40,16 @@ As well as processing text, SILE can also include images. Loading the \autodoc:package{image} package gives you the \autodoc:command{\img} command, fashioned after the HTML equivalent. It takes the following parameters: \autodoc:parameter{src=} must be the path to an image file; you may also give \autodoc:parameter{height} and/or \autodoc:parameter{width} parameters to specify the output size of the image on the paper. -If the size parameters are not given, then the image will be output at its ‘natural’ size, honoring its resolution if available. +If the size parameters are not given, then the image will be output at its “natural” size, honoring its resolution if available. The command also supports a \autodoc:parameter{page=} option, to specify the selected page in formats supporting several pages (such as PDF). \begin{note} -With the libtexpdf backend (the default), the images can be in JPEG, PNG, EPS or PDF formats. +With the libtexpdf backend (the default), the images can be in JPEG, PNG, EPS, or PDF formats. \end{note} Here is a 200x243 pixel image output with \autodoc:command{\img[src=documentation/gutenberg.png]}. -The image has a claimed resolution of 100 pixels per inch, so ends up being 2 inches (144pt) wide on the page:\par +The image has a claimed resolution of 100 pixels per inch, so ends up being two inches (144pt) wide on the page:\par \img[src=documentation/gutenberg.png] \raggedright{ diff --git a/packages/infonode/init.lua b/packages/infonode/init.lua index 66c5ccdee..fe6a1df1a 100644 --- a/packages/infonode/init.lua +++ b/packages/infonode/init.lua @@ -72,7 +72,7 @@ package.documentation = [[ While typesetting a document, SILE first breaks a paragraph into lines, then arranges lines into a page, and later outputs the page. In other words, while it is looking at the text of a paragraph, it is not clear what page the text will eventually end up on. -This makes it difficult to produce indexes, tables of contents and so on where one needs to know the page number for a particular element. +This makes it difficult to produce indexes, tables of contents, and so on, where one needs to know the page number for a particular element. To get around this problem, the \autodoc:package{infonode} package allows you to insert \em{information nodes} into the text stream; when a page is outputted, these nodes are collected into a list, and a class’s output routine can examine this list to determine which nodes fell on a particular page. \autodoc:package{infonode} provides the \autodoc:command{\info} command to put an information node into the text stream; it has two required parameters, \autodoc:parameter{category=} and \autodoc:parameter{value=}. diff --git a/packages/linespacing/init.lua b/packages/linespacing/init.lua index 677936640..0af66972f 100644 --- a/packages/linespacing/init.lua +++ b/packages/linespacing/init.lua @@ -167,14 +167,18 @@ By default, this is set to \code{tex}. The other options available are: \medskip \set[parameter=linespacing.method,value=fixed] \set[parameter=linespacing.fixed.baselinedistance,value=1.5em] -\noindent{}• \code{fixed}. This set the lines at a fixed baseline-to-baseline distance, determined by the \autodoc:setting{linespacing.fixed.baselinedistance} parameter. -You can specify this parameter either relative to the type size (e.g. \code{1.2em}) or as a absolute distance (\code{15pt}). -This paragraph is set with a fixed 1.5em baseline-to-baseline distance. +\begin{itemize} +\item{\code{fixed}. This set the lines at a fixed baseline-to-baseline distance, determined by the \autodoc:setting{linespacing.fixed.baselinedistance} parameter. +You can specify this parameter either relative to the type size (\code{1.2em}) or as a absolute distance (\code{15pt}). +This paragraph is set with a fixed 1.5em baseline-to-baseline distance.} +\end{itemize} \medskip \set[parameter=linespacing.method,value=fit-glyph] -\noindent{}• \code{fit-glyph}. This sets the lines solid; that is, the lowest point on line 1 (either a descender like \font[size=20pt]{q} or, if there are no descenders, the baseline) will touch the \font[size=20pt]{highest} point of line 2, as in this paragraph. -You generally don’t want to use this as is. +\begin{itemize} +\item{\code{fit-glyph}. This sets the lines solid; that is, the lowest point on line 1 (either a descender like \font[size=20pt]{q} or, if there are no descenders, the baseline) will touch the \font[size=20pt]{highest} point of line 2, as in this paragraph. +You generally don’t want to use this as-is.} +\end{itemize} \set[parameter=linespacing.fit-glyph.extra-space,value=5pt] @@ -183,10 +187,12 @@ What you probably want to do is insert a constant (relative or absolute) s\font[ \medskip \set[parameter=linespacing.method,value=fit-font] -\noindent{}• \code{fit-font}. This inspects each hbox on the line, and asks the fonts it finds for their bounding boxes - the highest ascender and the lower descender. +\begin{itemize} +\item{\code{fit-font}. This inspects each \code{hbox} on the line, and asks the fonts it finds for their bounding boxes—the highest ascender and the lower descender. It then sets the lines solid. Essentially each character is treated as if it is the same height, rather like composing a slug of metal type. -If there are things other than text on your line, or the text is buried inside other boxes, this may not work so well. +If there are things other than text on your line, or the text is buried inside other boxes, this may not work well.} +\end{itemize} \set[parameter=linespacing.fit-font.extra-space,value=5pt] @@ -195,7 +201,9 @@ As with \code{fit-glyph}, you can insert extra space between the lines with the \medskip \set[parameter=linespacing.method,value=css] \set[parameter=linespacing.css.line-height,value=2em] -\noindent{}• \code{css}. This is similar to the method used in browsers; the baseline distance is set with the \autodoc:setting{linespacing.css.line-height} parameter, and the excess \font[size=20pt]{space} between this parameter and the actual height of the line is distributed between the top and bottom of the line. +\begin{itemize} +\item{\code{css}. This is similar to the method used in browsers; the baseline distance is set with the \autodoc:setting{linespacing.css.line-height} parameter, and the excess \font[size=20pt]{space} between this parameter and the actual height of the line is distributed between the top and bottom of the line.} +\end{itemize} \medskip \linespacing-off diff --git a/packages/lists/init.lua b/packages/lists/init.lua index 0a9a0bd86..dd41400fe 100644 --- a/packages/lists/init.lua +++ b/packages/lists/init.lua @@ -280,16 +280,18 @@ end package.documentation = [[ \begin{document} \font:add-fallback[family=Symbola]% HACK Gentium Plus (SILE default font) lacks the circle bullet :( -The \autodoc:package{lists} package provides enumerations and bullet lists (a.k.a. \em{itemization}\kern[width=0.1em]) which can be nested together. +The \autodoc:package{lists} package provides enumerated and itemized (also known as \em{bulleted lists}) which can be nested together. \smallskip -\em{Bullet lists.} +\noindent +\em{Itemized lists} \novbreak -The \autodoc:environment{itemize} environment initiates a bullet list. -Each item is, as could be guessed, wrapped in an \autodoc:command{\item} command. +\indent +The \autodoc:environment{itemize} environment initiates a itemized list. +Each item, unsurprisingly, is wrapped in an \autodoc:command{\item} command. -The environment, as a structure or data model, can only contain item elements and other lists. +The environment, as a structure or data model, can only contain \code{item} elements or other lists. Any other element causes an error to be reported, and any text content is ignored with a warning. \begin{itemize} @@ -302,19 +304,20 @@ Any other element causes an error to be reported, and any text content is ignore \end{itemize} \end{itemize} -The current implementation supports up to 6 indentation levels. +The current implementation supports up to six indentation levels. -On each level, the indentation is defined by the \autodoc:setting{lists.itemize.leftmargin} setting (defaults to 1.5em) and the bullet is centered in that margin. +On each level, the indentation is defined by the \autodoc:setting{lists.itemize.leftmargin} setting (defaults to \code{1.5em}) and the bullet is centered in that margin. Note that if your document has a paragraph indent enabled at this point, it is also added to the first list level. -The package has a default style for each level, but you can explicitly select a bullet symbol of your choice to be used, by specifying the options \autodoc:parameter{bullet=}, on the \autodoc:environment{itemize} environment. - +The package has a default bullet style for each level, but you can explicitly select a bullet symbol of your choice to be used by specifying the options \autodoc:parameter{bullet=} on the \autodoc:environment{itemize} environment. You can also force a specific bullet character to be used on a specific item with \autodoc:command{\item[bullet=]}. \smallskip -\em{Enumerations.} +\noindent +\em{Enumerated lists} \novbreak +\indent The \autodoc:environment{enumerate} environment initiates an enumeration. Each item shall, again, be wrapped in an \autodoc:command{\item} command. This environment too is regarded as a structure, so the same rules as above apply. @@ -331,26 +334,29 @@ The enumeration starts at one, unless you specify the \autodoc:parameter{start=< \end{enumerate} \end{enumerate} -The current implementation supports up to 6 indentation levels. +The current implementation supports up to six indentation levels. -On each level, the indentation is defined by the \autodoc:setting{lists.enumerate.leftmargin} setting (defaults to 2em). +On each level, the indentation is defined by the \autodoc:setting{lists.enumerate.leftmargin} setting (defaults to \code{2em}). Note, again, that if your document has a paragraph indent enabled at this point, it is also added to the first list level. -And… ah, at least something less repetitive than a raw list of features. -\em{Quite obviously}, we cannot center the label. -Roman numbers, folks, if any reason is required. -The \autodoc:setting{lists.enumerate.labelindent} setting specifies the distance between the label and the previous indentation level (defaults to 0.5em). + +% And… ah, at least something less repetitive than a raw list of features. +% \em{Quite obviously}, we cannot center the label. +% Roman numbers, folks, if any reason is required. + +The \autodoc:setting{lists.enumerate.labelindent} setting specifies the distance between the label and the previous indentation level (defaults to \code{0.5em}). Tune these settings at your convenience depending on your styles. -If there is a more general solution to this subtle issue, this author accepts patches. -\footnote{TeX typesets the enumeration label ragged left. Other Office software do not.} +If there is a more general solution to this subtle issue, we accept patches.% +\footnote{TeX typesets the enumeration label ragged left. Most word processing software do not.} -The package has a default style for each level, but you can explicitly select the display type (format) of the values (as “arabic”, “roman”, etc.), and the text prepended or appended to them, by specifying the options \autodoc:parameter{display=}, \autodoc:parameter{before=}, and \autodoc:parameter{after=} to the \autodoc:environment{enumerate} environment. +The package has a default number style for each level, but you can explicitly select the display type (format) of the values (as \code{arabic}, \code{roman}, or \code{alpha}), and the text prepended or appended to them, by specifying the options \autodoc:parameter{display=}, \autodoc:parameter{before=}, and \autodoc:parameter{after=} to the \autodoc:environment{enumerate} environment. \smallskip - -\em{Nesting.} +\noindent +\em{Nesting} \novbreak -Both environment can be nested, \em{of course}. +\indent +Both environments can be nested. The way they do is best illustrated by an example. \begin{enumerate} @@ -370,21 +376,23 @@ The way they do is best illustrated by an example. \end{enumerate} \smallskip - -\em{Vertical spaces.} +\noindent +\em{Vertical spaces} \novbreak +\indent The package tries to ensure a paragraph is enforced before and after a list. In most cases, this implies paragraph skips to be inserted, with the usual \autodoc:setting{document.parskip} glue, whatever value it has at these points in the surrounding context of your document. Between list items, however, the paragraph skip is switched to the value of the \autodoc:setting{lists.parskip} setting. \smallskip - -\em{Other considerations.} +\noindent +\em{Other considerations} \novbreak +\indent Do not expect these fragile lists to work in any way in centered or ragged-right environments, or with fancy line-breaking features such as hanged or shaped paragraphs. -Please be a good typographer. Also, these lists have not been experimented yet in right-to-left or vertical writing direction. +Please be a good typographer. Also, these lists have not yet been tried in right-to-left or vertical writing direction. \font:remove-fallback \end{document} diff --git a/packages/masters/init.lua b/packages/masters/init.lua index fa45b53ca..664c7b3fa 100644 --- a/packages/masters/init.lua +++ b/packages/masters/init.lua @@ -123,7 +123,7 @@ package.documentation = [[ \begin{document} The masters functionality is also itself an add-on package. It allows a class to define sets of frames and switch between them either temporarily or permanently. -It defines the commands \autodoc:command{\define-master-template} (which is pattern on the \autodoc:command{\pagetemplate} function we will meet in chapter 8), \autodoc:command{\switch-master} and \autodoc:command{\switch-master-one-page}. +It defines the commands \autodoc:command{\define-master-template} (which is patterned on the \autodoc:command{\pagetemplate} function we will meet in Chapter 8), \autodoc:command{\switch-master}, and \autodoc:command{\switch-master-one-page}. See \code{tests/masters.sil} for more about this package. \end{document} ]] diff --git a/packages/math/init.lua b/packages/math/init.lua index b384ce74c..b7ad7be2a 100644 --- a/packages/math/init.lua +++ b/packages/math/init.lua @@ -100,18 +100,19 @@ This package provides typesetting of formulas directly in a SILE document. As such, it lacks some features and may contain bugs. Feedback and contributions are always welcome.} -\noindent To typeset mathematics, you will need an OpenType math font installed on your system\footnote{A list of freely available math fonts can be found at \href[src=https://www.ctan.org/pkg/unicode-math]{https://www.ctan.org/pkg/unicode-math}}. +\noindent To typeset mathematics, you will need an OpenType math font installed on your system.% +%\footnote{A list of freely available math fonts can be found at \href[src=https://www.ctan.org/pkg/unicode-math]{https://www.ctan.org/pkg/unicode-math}} By default, this package uses Libertinus Math, so it will fail if Libertinus Math can’t be found. Another font may be specified via the setting \autodoc:setting{math.font.family}. -If required the font style and weight can be set via \autodoc:setting{math.font.style} and \autodoc:setting{math.font.weight}. +If required, you can set the font style and weight via \autodoc:setting{math.font.style} and \autodoc:setting{math.font.weight}. The font size can be set via \autodoc:setting{math.font.size}. \paragraph{MathML} The first way to typeset math formulas is to enter them in the MathML format. MathML is a standard for encoding mathematical notation for the Web and for other types of digital documents. -It is supported by a wide range of tools and represents the most promising format for unifying the encoding of mathematical notation, as well as improving its accessibility (e.g. to blind users). +It is supported by a wide range of tools and represents the most promising format for unifying the encoding of mathematical notation, as well as improving its accessibility (e.g., to blind users). -To render an equation encoded in MathML, one simply has to put it in a \code{mathml} command. +To render an equation encoded in MathML, simply put it in a \code{mathml} command. For example, the formula \mathml{\mrow{\msup{\mi{a}\mn{2}} \mo{+} \msup{\mi{b}\mn{2}} \mo{=} \msup{\mi{c}\mn{2}}}} was typeset by the following command: \begin[type=autodoc:codeblock]{raw} @@ -126,7 +127,7 @@ For example, the formula \mathml{\mrow{\msup{\mi{a}\mn{2}} \mo{+} \msup{\mi{b}\m } \end{raw} -\noindent In an XML document, we would have used the more classical XML syntax: +\noindent In an XML document, we could use the more classical XML syntax: \begin[type=autodoc:codeblock]{raw} @@ -141,7 +142,7 @@ For example, the formula \mathml{\mrow{\msup{\mi{a}\mn{2}} \mo{+} \msup{\mi{b}\m \end{raw} \noindent By default, formulas are integrated into the flow of text. -To typeset them on their own line, one may use the \autodoc:parameter{mode=display} option: +To typeset them on their own line, use the \autodoc:parameter{mode=display} option: \mathml[mode=display]{ \mrow{ @@ -175,12 +176,12 @@ Here is a slightly more involved equation: The general philosophy of the TeX-like syntax is to be a simple layer on top of MathML, and not to mimic perfectly the syntax of the LaTeX tool. Its main difference from the SILE syntax is that \code{\\mycommand\{arg1\}\{arg2\}\{arg3\}} is translated into MathML as \code{ arg1 arg2 arg3 } whereas in normal SILE syntax, the XML equivalent would be \code{arg1 arg2 arg3}. -\code{\\sum}, \code{\\infty} and \code{\\pi} are only shorthands for the Unicode characters \math{\sum}, \math{\infty} and \math{\pi}. +\code{\\sum}, \code{\\infty}, and \code{\\pi} are only shorthands for the Unicode characters \math{\sum}, \math{\infty} and \math{\pi}. If it’s more convenient, you can use these Unicode characters directly. The symbol shorthands are the same as in the TeX package \href[src=https://www.ctan.org/pkg/unicode-math]{\code{unicode-math}}. -\code{\{formula\}} is a shorthand for \code{\\mrow\{formula\}}. -Since parentheses — among other glyphs — stretch vertically to the size of their englobing \code{mrow}, this is useful to typeset parentheses of different sizes on the same line: +\code{\\\{formula\}} is a shorthand for \code{\\mrow\{formula\}}. +Since parentheses—among other glyphs—stretch vertically to the size of their englobing \code{mrow}, this is useful to typeset parentheses of different sizes on the same line: \begin[type=autodoc:codeblock]{raw} \Gamma (\frac{\zeta}{2}) + x^2(x+1) @@ -207,7 +208,7 @@ To keep parentheses around \math{x+1} small, you should put braces around the ex \paragraph{Token kinds} In the \code{math} syntax, every individual letter is an identifier (MathML tag \code{mi}), every number is a… number (tag \code{mn}) and all other characters are operators (tag \code{mo}). -If it does not suit you, you can explicitly use the \code{\\mi}, \code{\\mn} or \code{\\mo} tags. +If this does not suit you, you can explicitly use the \code{\\mi}, \code{\\mn}, or \code{\\mo} tags. For instance, \code{sin(x)} will be rendered as \math{sin(x)}, because SILE considers the letters s, i and n to be individual identifiers, and identifiers made of one character are italicized by default. To avoid that, you can specify that \math{\mi{sin}} is an identifier by writing \code{\\mi\{sin\}(x)} and get: \math{\mi{sin}(x)}. If you prefer it in “double struck” style, this is permitted by the \code{mathvariant} attribute: \code{\\mi[mathvariant=double-struck]\{sin\}(x)} renders as \math{\mi[mathvariant=double-struck]{sin}(x)}. @@ -215,13 +216,13 @@ If you prefer it in “double struck” style, this is permitted by the \code{ma \paragraph{Atom types and spacing} Each token automatically gets assigned an atom type from the list below: \begin{itemize} - \item{\code{ord} — \code{mi} and \code{mn} tokens, as well as unclassified operators;} - \item{\code{big} — big operators like ‘\math{\sum}’ or ‘\math{\prod}’;} - \item{\code{bin} — binary operators like ‘\math{+}’ or ‘\math{\%}’;} - \item{\code{rel} — relation operators like ‘\math{=}’ or ‘\math{<}’;} - \item{\code{open} — opening operators like ‘\math{(}’ or ‘\math{[}’;} - \item{\code{close} — closing operators like ‘\math{)}’ or ‘\math{]}’;} - \item{\code{punct} — punctuation operators like ‘\math{,}’.} + \item{\code{ord}: \code{mi} and \code{mn} tokens, as well as unclassified operators} + \item{\code{big}: big operators like ‘\math{\sum}’ or ‘\math{\prod}’} + \item{\code{bin}: binary operators like ‘\math{+}’ or ‘\math{\%}’} + \item{\code{rel}: relation operators like ‘\math{=}’ or ‘\math{<}’} + \item{\code{open}: opening operators like ‘\math{(}’ or ‘\math{[}’} + \item{\code{close}: closing operators like ‘\math{)}’ or ‘\math{]}’} + \item{\code{punct}: punctuation operators like ‘\math{,}’} % TODO: Those are defined in the 'math' package but appear to be unused %\item{\code{inner}} %\item{\code{over}} @@ -231,13 +232,13 @@ Each token automatically gets assigned an atom type from the list below: %\item{\code{vcenter}} \end{itemize} \noindent The spacing between any two successive tokens is set automatically based on their atom types, and hence may not reflect the actual spacing used in the input. -To make an operator behave like it has a certain atom type, you can use the \code{atom} attribute: \code{a \\mo[atom=bin]\{div\} b} renders as \math[mode=display]{a \mo[atom=bin]{div} b.} +To make an operator behave like it has a certain atom type, you can use the \code{atom} attribute. For example, \code{a \\mo[atom=bin]\{div\} b} renders as \math[mode=display]{a \mo[atom=bin]{div} b.} Spaces in math mode are defined in “math units” (mu), which are 1/18 of an em of the current \em{math} font (and are independent of the current text font size). Standard spaces inserted automatically between tokens come in three varieties: thin (3 mu), medium (4 mu) and thick (5 mu). If needed, you can insert them manually with the \code{\\thinspace} (or \code{\\,}), \code{\\medspace} (or \code{\\>}), and \code{\\thickspace} (or \code{\\;}) commands. Negative space counterparts are available as \code{\\negthinspace} (or \code{\\!}), \code{\\negmedspace}, and \code{\\negthickspace}. -The \code{\\enspace}, \code{\\quad} and \code{\\qquad} commands from normal text mode are also available, but the spaces they insert scale relative to the text font size. +The \code{\\enspace}, \code{\\quad}, and \code{\\qquad} commands from normal text mode are also available, but the spaces they insert scale relative to the text font size. Finally, you can add a space of any size using the \code{\\mspace[width=]} command. \paragraph{Macros} @@ -269,7 +270,7 @@ For instance: When macros are not enough, creating new mathematical elements is quite simple: one only needs to create a new class deriving from \code{mbox} (defined in \code{packages/math/base-elements.lua}) and define the \code{shape} and \code{output} methods. \code{shape} must define the \code{width}, \code{height} and \code{depth} attributes of the element, while \code{output} must draw the actual output. -An \code{mbox} may have one or more children (for instance, a fraction has two children — its numerator and denominator). +An \code{mbox} may have one or more children (for instance, a fraction has two children—its numerator and denominator). The \code{shape} and \code{output} methods of the children are called automatically. \paragraph{Matrices, aligned equations, and other tables} diff --git a/packages/parallel/init.lua b/packages/parallel/init.lua index 78bdc3cb0..9f8b674a5 100644 --- a/packages/parallel/init.lua +++ b/packages/parallel/init.lua @@ -146,7 +146,7 @@ package.documentation = [[ The \autodoc:package{parallel} package provides the mechanism for typesetting diglot or other parallel documents. When used by a class such as \code{classes/diglot.lua}, it registers a command for each parallel frame, to allow you to select which frame you’re typesetting into. It also defines the \autodoc:command{\sync} command, which adds vertical spacing to each frame such that the \em{next} set of text is vertically aligned. -See \url{https://sile-typesetter.org/examples/parallel.sil} and the source of \code{classes/diglot.lua} for examples which makes the operation clear. +See \url{https://sile-typesetter.org/examples/parallel.sil} and the source of \code{classes/diglot.lua} for examples which make the operation clear. \end{document} ]] diff --git a/packages/pdf/init.lua b/packages/pdf/init.lua index 92f96a1b0..6e4f90e33 100644 --- a/packages/pdf/init.lua +++ b/packages/pdf/init.lua @@ -167,13 +167,13 @@ end package.documentation = [[ \begin{document} -The \autodoc:package{pdf} package enables (basic) support for PDF links and table-of-contents entries. +The \autodoc:package{pdf} package enables basic support for PDF links and table-of-contents entries. It provides the four commands \autodoc:command{\pdf:destination}, \autodoc:command{\pdf:link}, \autodoc:command{\pdf:bookmark}, and \autodoc:command{\pdf:metadata}. The \autodoc:command{\pdf:destination} parameter creates a link target; it expects a parameter called \autodoc:parameter{name} to uniquely identify the target. To create a link to that location in the document, use \autodoc:command{\pdf:link[dest=]{}}. -The \autodoc:command{\pdf:link} command accepts several options defining its border style: a \autodoc:parameter{borderwidth} length setting the border width (defaults to 0, meaning no border), a \autodoc:parameter{borderstyle} string (can be set to “underline” or “dashed”, otherwise a solid box), a \autodoc:parameter{bordercolor} color specification for this border (defaults to blue), and finally a \autodoc:parameter{borderoffset} length for adjusting the border with some vertical space above the content and below the baseline (defaults to 1pt). +The \autodoc:command{\pdf:link} command accepts several options defining its border style: a \autodoc:parameter{borderwidth} length setting the border width (defaults to \code{0}, meaning no border), a \autodoc:parameter{borderstyle} string (can be set to \code{underline} or \code{dashed}, otherwise a solid box), a \autodoc:parameter{bordercolor} color specification for this border (defaults to \code{blue}), and finally a \autodoc:parameter{borderoffset} length for adjusting the border with some vertical space above the content and below the baseline (defaults to \code{1pt}). Note that PDF renderers may vary on how they honor these border styling features on link annotations. It also has an \autodoc:parameter{external} option for URL links, which is not intended to be used directly—refer to the \autodoc:package{url} package for more flexibility typesetting external links. diff --git a/packages/pullquote/init.lua b/packages/pullquote/init.lua index ab7412105..b77210af2 100644 --- a/packages/pullquote/init.lua +++ b/packages/pullquote/init.lua @@ -80,7 +80,7 @@ package.documentation = [[ \begin{document} The \autodoc:environment{pullquote} environment formats longer quotations in an indented blockquote block with decorative quotation marks in the margins. -Here is some text set in a pullquote environment: +Here is some text set in a \autodoc:environment{pullquote} environment: \begin[author=Anatole France]{pullquote}% An education is not how much you have committed to memory, or even how much you know. @@ -90,15 +90,15 @@ It is being able to differentiate between what you do know and what you do not k Optional values are available for: \begin{itemize} -\item{\autodoc:parameter{author} to add an attribution line,} -\item{\autodoc:parameter{setback} to set the bilateral margins around the block,} -\item{\autodoc:parameter{color} to change the color of the quote marks,} -\item{\autodoc:parameter{scale} to change the relative size of the quote marks.} +\item{\autodoc:parameter{author} to add an attribution line} +\item{\autodoc:parameter{setback} to set the bilateral margins around the block} +\item{\autodoc:parameter{color} to change the color of the quote marks} +\item{\autodoc:parameter{scale} to change the relative size of the quote marks} \end{itemize} -If you want to specify what font the pullquote environment should use, you can redefine the \autodoc:command{\pullquote:font} command. +If you want to specify what font the \autodoc:environment{pullquote} environment should use, you can redefine the \autodoc:command{\pullquote:font} command. By default it will be the same as the surrounding document. -The font style used for the attribution line can likewise be set redefining \autodoc:command{\pullquote:author-font} and the font used for the quote marks can be set redefining \autodoc:command{\pullquote:mark-font}. +The font style used for the attribution line can likewise be set redefining \autodoc:command{\pullquote:author-font}, and the font used for the quote marks can be set redefining \autodoc:command{\pullquote:mark-font}. \end{document} ]] diff --git a/packages/raiselower/init.lua b/packages/raiselower/init.lua index 98f60d2b3..63b3183de 100644 --- a/packages/raiselower/init.lua +++ b/packages/raiselower/init.lua @@ -36,10 +36,10 @@ end package.documentation = [[ \begin{document} -If you don’t want your images, rules or text to be placed along the baseline, you can use the \autodoc:package{raiselower} package to move them up and down. +If you don’t want your images, rules, or text to be placed along the baseline, you can use the \autodoc:package{raiselower} package to move them up and down. (The \autodoc:package{footnote} package uses this to superscript the footnote reference numbers.) -It provides two simple commands, \autodoc:command{\raise} and \autodoc:command{\lower} which both take a \autodoc:parameter{height=} parameter. +It provides two simple commands, \autodoc:command{\raise} and \autodoc:command{\lower}, which both take a \autodoc:parameter{height=} parameter. They will respectively raise or lower their argument by the given height. The raised or lowered content will not alter the height or depth of the line. diff --git a/packages/rebox/init.lua b/packages/rebox/init.lua index 062b37893..d56147824 100644 --- a/packages/rebox/init.lua +++ b/packages/rebox/init.lua @@ -24,7 +24,7 @@ end package.documentation = [[ \begin{document} This package provides the \autodoc:command{\rebox} command, which allows you to lie to SILE about the size of content. -You can change the \autodoc:parameter{width}, \autodoc:parameter{height}, or \autodoc:parameter{depth} of your content with the respective parameters, or make it invisible by setting the \autodoc:parameter{phantom} parameter to true. +You can change the \autodoc:parameter{width}, \autodoc:parameter{height}, or \autodoc:parameter{depth} of your content with the respective parameters, or make it invisible by setting the \autodoc:parameter{phantom} parameter to \code{true}. For example: diff --git a/packages/rotate/init.lua b/packages/rotate/init.lua index 7e39dd3f8..c7420cf00 100644 --- a/packages/rotate/init.lua +++ b/packages/rotate/init.lua @@ -115,15 +115,15 @@ where the angle is measured in degrees. Content which is rotated is placed in a box and rotated. The height and width of the rotated box is measured, and then put into the normal horizontal list for -typesetting. The effect of this is that space is reserved around the rotated content. +typesetting. The effect is that space is reserved around the rotated content. The best way to understand this is by example: here is some text rotated by -\rotate[angle=10]{ten}, \rotate[angle=20]{twenty} and \rotate[angle=40]{forty} degrees. +\rotate[angle=10]{ten}, \rotate[angle=20]{twenty}, and \rotate[angle=40]{forty} degrees. The previous line was produced by the following code: \begin[type=autodoc:codeblock]{raw} here is some text rotated by -\rotate[angle=10]{ten}, \rotate[angle=20]{twenty} and \rotate[angle=40]{forty} degrees. +\rotate[angle=10]{ten}, \rotate[angle=20]{twenty}, and \rotate[angle=40]{forty} degrees. \end{raw} \end{document} ]] diff --git a/packages/rules/init.lua b/packages/rules/init.lua index 2aaa6f7b3..f99bef3d4 100644 --- a/packages/rules/init.lua +++ b/packages/rules/init.lua @@ -253,23 +253,23 @@ package.documentation = [[ \begin{document} The \autodoc:package{rules} package provides several line-drawing commands. -The \autodoc:command{\hrule} command draws a blob of ink of a given \autodoc:parameter{width} (length), \autodoc:parameter{height} (above the current baseline) and \autodoc:parameter{depth} (below the current baseline). +The \autodoc:command{\hrule} command draws a blob of ink of a given \autodoc:parameter{width} (length), \autodoc:parameter{height} (above the current baseline), and \autodoc:parameter{depth} (below the current baseline). Such rules are horizontal boxes, placed along the baseline of a line of text and treated just like other text to be output. So, they can appear in the middle of a paragraph, like this: \hrule[width=20pt, height=0.5pt] -(that one was generated with \autodoc:command{\hrule[width=20pt, height=0.5pt]}.) +(That one was generated with \autodoc:command{\hrule[width=20pt, height=0.5pt]}.) The \autodoc:command{\underline} command \underline{underlines} its content. The \autodoc:command{\strikethrough} command \strikethrough{strikes} its content. -\note{The position and thickness of the underlines and strikethroughs are based on then current font metrics, honoring the values defined by the type designer.} +\note{The position and thickness of the underlines and strikethroughs are based on the metrics of the current font, honoring the values defined by the type designer.} -The \autodoc:command{\hrulefill} inserts an infinite horizontal rubber, similar to an \autodoc:command{\hfill}, but —as its name implies— filled with a rule (that is, a solid line). +The \autodoc:command{\hrulefill} inserts an infinite horizontal rubber, similar to an \autodoc:command{\hfill}, but—as its name implies—filled with a rule (that is, a solid line). By default, it stands on the baseline and has a thickness of 0.2pt, below the baseline. It supports optional parameters \autodoc:parameter{raise=} and \autodoc:parameter{thickness=} to adjust the position and thickness of the line, respectively. The former accepts a negative measurement, to lower the line. -An alternative is to use the \autodoc:parameter{position} option, which can be set to \code{underline} or \code{strikethrough}. +Alternatively, use the \autodoc:parameter{position} option, which can be set to \code{underline} or \code{strikethrough}. In that case, it honors the current font metrics and the line is drawn at the appropriate position and, by default, with the relevant thickness. You can still set a custom thickness with the \autodoc:parameter{thickness} parameter. diff --git a/packages/tableofcontents/init.lua b/packages/tableofcontents/init.lua index cf6bf1ea9..98d987a0d 100644 --- a/packages/tableofcontents/init.lua +++ b/packages/tableofcontents/init.lua @@ -221,16 +221,16 @@ end package.documentation = [[ \begin{document} The \autodoc:package{tableofcontents} package provides tools for class authors to -create tables of contents. When you are writing sectioning commands such +create tables of contents (TOCs). When you are writing sectioning commands such as \code{\\chapter} or \code{\\section}, your classes should call the \autodoc:command{\tocentry[level=, number=]{}} command to register a table of contents entry. -At the end of each page the class will call a hook function (\code{moveTocNodes}) that collates the table of contents entries from that pages and logs which page they’re on. +At the end of each page the class will call a hook function (\code{moveTocNodes}) that collates the table of contents entries from that pages and records which page they’re on. At the end of the document another hook function (\code{writeToc}) will write this data to a file. The next time the document is built, any use of the \autodoc:command{\tableofcontents} (typically near the beginning of a document) will be able to read that index data and output the TOC. Because the toc entry and page data is not available until after rendering the document, the TOC will not render until at least the second pass. -If by chance rendering the TOC itself changes the document pagination (e.g. the TOC spans more than one page) it might be necessary to run SILE 3 times to get accurate page numbers shown in the TOC. +If by chance rendering the TOC itself changes the document pagination (e.g., the TOC spans more than one page) it might be necessary to run SILE three times to get accurate page numbers shown in the TOC. The \autodoc:command{\tableofcontents} command accepts a \autodoc:parameter{depth} option to @@ -246,11 +246,11 @@ Class designers can also style the table of contents by overriding the following commands: \begin{itemize} -\item{\autodoc:command{\tableofcontents:headerfont} - the font used for the header.} +\item{\autodoc:command{\tableofcontents:headerfont}: The font used for the header.} \item{\autodoc:command{\tableofcontents:level1item}, \autodoc:command{\tableofcontents:level2item}, - etc. - styling for entries.} + etc.: Styling for entries.} \item{\autodoc:command{\tableofcontents:level1number}, \autodoc:command{\tableofcontents:level2number}, - etc. - deciding what to do with entry section number, if defined: by default, nothing (so they + etc.: Deciding what to do with entry section number, if defined: by default, nothing (so they do not show up in the table of contents).} \end{itemize} diff --git a/packages/twoside/init.lua b/packages/twoside/init.lua index 2447d282b..b833bcda1 100644 --- a/packages/twoside/init.lua +++ b/packages/twoside/init.lua @@ -134,22 +134,22 @@ end package.documentation = [[ \begin{document} -The \code{book} class described in chapter 4 sets up left and right mirrored page masters; the \autodoc:package{twoside} package is responsible for swapping between the two left and right frames, running headers and so on. -It's main function in mirroring master frames does not provide any user-serviceable parts. -It does supply a couple user facing commands for convenience. +The \code{book} class described in Chapter 4 sets up left and right mirrored page masters; the \autodoc:package{twoside} package is responsible for swapping between the two left and right frames, running headers, and so on. +Its main function in mirroring master frames does not provide any user-serviceable parts. +It does supply a few user-facing commands for convenience. -The \autodoc:command{\open-double-page} ejects whatever page is currently being processed, then checks if it landed on an odd page. -If so it does nothing, but if not it ejects another page to assure content starts on an odd page. +The \autodoc:command{\open-double-page} ejects whatever page is currently being processed, then checks if it landed on an even page. +If so, it ejects another page to assure content starts on an odd page. The \autodoc:command{\open-spread} is similar but a bit more tailored to use in book layouts. -By default headers and folios will be suppressed automatically on any empty pages ejected, making them blank. +By default, headers and folios will be suppressed automatically on any empty pages ejected, making them blank. It can also accept three parameters. -The \autodoc:parameter{odd=false} parameter can be used to disable the opening page being odd, hence opening an even page spread. -The \autodoc:parameter{double=false} parameter can be used to always output at least one empty even page before the starting an odd page. -The \autodoc:parameter{blank=false} parameter can be used to not suppress headers and folios on otherwise empty pages. +The \autodoc:parameter{odd} parameter (default \code{false}) can be used to disable the opening page being odd, hence opening an even page spread. +The \autodoc:parameter{double} parameter (default \code{false}) can be used to always output at least one empty even page before the starting an odd page. +The \autodoc:parameter{blank} parameter (default \code{false}) can be used to not suppress headers and folios on otherwise empty pages. Lastly the \autodoc:command{\open-spread-eject} command can be overridden to customize the output of blank pages. -By default it just runs \autodoc:command{\supereject}, but you could potentially add decorative content or other features in the otherwise dead space. +By default it just runs \autodoc:command{\supereject}, but you could potentially add decorative content or other features in the otherwise empty space. \end{document} ]] diff --git a/packages/unichar/init.lua b/packages/unichar/init.lua index 8414e0840..b9640f415 100644 --- a/packages/unichar/init.lua +++ b/packages/unichar/init.lua @@ -38,7 +38,7 @@ After loading \autodoc:package{unichar}, the \autodoc:command{\unichar} command This produces: \font[family=Symbola]{\unichar{U+263A}} -If the argument to \autodoc:command{\unichar} begins \code{U+}, \code{u+}, \code{0x} or \code{0X}, then it is assumed to be a hexadecimal value. +If the argument to \autodoc:command{\unichar} begins with \code{U+}, \code{u+}, \code{0x}, or \code{0X}, then it is assumed to be a hexadecimal value. Otherwise it is assumed to be a decimal codepoint. \end{document} ]] diff --git a/packages/url/init.lua b/packages/url/init.lua index 31f93bfc6..556619e7c 100644 --- a/packages/url/init.lua +++ b/packages/url/init.lua @@ -163,7 +163,7 @@ package.documentation = [[ This package enhances the typesetting of URLs in two ways. First, it provides the \autodoc:command{\href[src=<url>]{<content>}} command which inserts PDF hyperlinks, \href[src=http://www.sile-typesetter.org/]{like this}. -The \autodoc:command{\href} command accepts the same \autodoc:parameter{borderwidth}, \autodoc:parameter{bordercolor}, \autodoc:parameter{borderstyle} and \autodoc:parameter{borderoffset} styling options as the \autodoc:command[check=false]{\pdf:link} command from the \autodoc:package{pdf} package, for instance \href[src=http://www.sile-typesetter.org/, borderwidth=0.4pt, bordercolor=blue, borderstyle=underline]{like this}. +The \autodoc:command{\href} command accepts the same \autodoc:parameter{borderwidth}, \autodoc:parameter{bordercolor}, \autodoc:parameter{borderstyle}, and \autodoc:parameter{borderoffset} styling options as the \autodoc:command[check=false]{\pdf:link} command from the \autodoc:package{pdf} package, for instance \href[src=http://www.sile-typesetter.org/, borderwidth=0.4pt, bordercolor=blue, borderstyle=underline]{like this}. Nowadays, it is a common practice to have URLs in print articles (whether it is a good practice or not is yet \em{another} topic). Therefore, the package also provides the \autodoc:command{\url} command, which will automatically insert breakpoints into unwieldy URLs like \url{https://github.com/sile-typesetter/sile-typesetter.github.io/tree/master/examples} so that they can be broken up over multiple lines. @@ -173,10 +173,10 @@ By default, the \autodoc:command{\url} command ignores the current language, as If you have no other choice, however, you can pass it a \autodoc:parameter{language} option to enforce a language to be applied. Note that if French (\code{fr}) is selected, the special typographic rules applying to punctuations in this language are disabled. -To typeset an URL and at the same type have it as active hyperlink, one can use the \autodoc:command{\href} command without the \autodoc:parameter{src} option, +To typeset a URL and also make it an active hyperlink, use the \autodoc:command{\href} command without the \autodoc:parameter{src} option, but with the URL passed as argument. -The breaks are controlled by two penalty settings, \autodoc:setting{url.linebreak.primaryPenalty} for preferred breakpoints and, for less acceptable but still tolerable breakpoints, \autodoc:setting{url.linebreak.secondaryPenalty} —its value should logically be higher than the previous one. +The breaks are controlled by two penalty settings: \autodoc:setting{url.linebreak.primaryPenalty} for preferred breakpoints and, for less acceptable but still tolerable breakpoints, \autodoc:setting{url.linebreak.secondaryPenalty}—its value should logically be higher than the previous one. \end{document} ]] diff --git a/packages/xmltricks/init.lua b/packages/xmltricks/init.lua index 1f4c7cd1e..ec74d6412 100644 --- a/packages/xmltricks/init.lua +++ b/packages/xmltricks/init.lua @@ -21,7 +21,7 @@ end package.documentation = [[ \begin{document} -In chapter 9, we’re going to use SILE to typeset existing XML documents. +In Chapter 9, we’re going to use SILE to typeset existing XML documents. Most of the work of typesetting XML with SILE is creating processing expectations for particular XML tags. \autodoc:package{xmltricks} makes the process somewhat easier by providing commands to handle two common cases. diff --git a/sile.1.in b/sile.1.in index 8aca422da..3fdc46541 100644 --- a/sile.1.in +++ b/sile.1.in @@ -55,7 +55,7 @@ May be specified more than once. .BR \-f ", " \-\-fontmanager= \fIvalue\fR Choose an alternative font manager. The font manager is responsible for discovering the locations on font files on the system given a font name. -The default font manager is \fIfontconfig\fR on non-Mac systems and \fImacfonts\fR on OS X. +The default font manager is \fIfontconfig\fR on non-macOS systems and \fImacfonts\fR on macOS. .TP .BR \-m ", " \-\-makedeps \fIfile\fR Generate a list of dependencies in Makefile format. From 5d21a3e44dc29d3ede910ed57fe267061db49a8a Mon Sep 17 00:00:00 2001 From: Caleb Maclennan <caleb@alerque.com> Date: Thu, 23 Mar 2023 21:52:14 +0300 Subject: [PATCH 14/14] docs(manual): Touchup minor details in copy-editing Co-authored-by: Omikhleia <didier.willis@gmail.com> --- documentation/c01-whatis.sil | 5 +++-- documentation/c08-language.sil | 6 +++--- documentation/c09-concepts.sil | 2 +- documentation/c10-classdesign.sil | 2 +- documentation/c11-xmlproc.sil | 4 ++-- documentation/c12-tricks.sil | 4 ++-- packages/date/init.lua | 3 ++- packages/math/init.lua | 2 +- packages/tableofcontents/init.lua | 3 +-- packages/twoside/init.lua | 6 +++--- 10 files changed, 19 insertions(+), 18 deletions(-) diff --git a/documentation/c01-whatis.sil b/documentation/c01-whatis.sil index 78173bc75..fe6a569a9 100644 --- a/documentation/c01-whatis.sil +++ b/documentation/c01-whatis.sil @@ -96,7 +96,8 @@ alter the behaviour of the SILE typesetter. For instance, one of the things that TeX can’t do particularly well is typesetting on a grid. This a must-have feature for anyone -typesetting bibles and other complicated documents. Typesetting on a grid means that each line of text will +typesetting bibles and other documents to be printed on thin paper. +Typesetting on a grid means that each line of text will line up between the front and back of each piece of paper producing much less visual bleed-through when printed on thin paper. This is virtually impossible to accomplish in TeX. There are various hacks to try to make it happen, but @@ -163,7 +164,7 @@ SILE. \section{Conclusion} SILE\footnote{In case you’re wondering, the author pronounces it -\font[family=Gentium Plus]{/saɪəl/}, to rhyme with “trial.”} {}takes some textual +\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 diff --git a/documentation/c08-language.sil b/documentation/c08-language.sil index 111942d85..bb3d29a16 100644 --- a/documentation/c08-language.sil +++ b/documentation/c08-language.sil @@ -61,7 +61,7 @@ To describe this, SILE uses the concept of a \em{writing direction,} which denotes the way each individual line appears on the page—left to right for Latin scripts, right to left for Arabic, Hebrew and so on, top to bottom for traditional Japanese—and a \em{page advance direction,} -which denotes the way the lines “stack up.” Each of these directions can +which denotes the way the lines “stack up”. Each of these directions can take one of four values: \code{LTR}, \code{RTL}, \code{TTB}, or \code{BTT}. A \em{direction specification} is made up of either a writing direction (\code{LTR} or \code{RTL}), in which case the page advance direction is @@ -180,9 +180,9 @@ or \code{centered} to control which style is used. The default is \code{left}. Esperanto typesetting is quite straight forward; however one feature of the language is unique: the requirement that \em{all} adjectives, including numerals, have the suffix “\eo{ª}”. This includes numbers standing on their own. -For example, “the 15th of March” is, in Esperanto, “\eo{la 15ª de marto}.” +For example, “the 15th of March” is, in Esperanto, “\eo{la 15ª de marto}”. As there is lack of agreement% -\footnote{Wikipedia prefers “\eo{15-a}” while most professional books and posters prefer “\eo{15ª}.” Some authors even write “\eo{15a},” as the underlying word is “\eo{dekkvina}.”} +\footnote{Wikipedia prefers “\eo{15-a}” while most professional books and posters prefer “\eo{15ª}”. Some authors even write “\eo{15a}”, as the underlying word is “\eo{dekkvina}”.} on how to typeset this, you have options: \autodoc:setting[check=false]{languages.eo.ordinal.raisedsuffix} when made true will use \eo{ª} (as in “\eo{Ĉapitro 1ª}”) while \autodoc:setting[check=false]{languages.eo.ordinal.hyphenbefore} will prepend a hyphen (as in “\eo{Ĉapitro 15-a}”). diff --git a/documentation/c09-concepts.sil b/documentation/c09-concepts.sil index 81023802f..5aeaf7d93 100644 --- a/documentation/c09-concepts.sil +++ b/documentation/c09-concepts.sil @@ -88,7 +88,7 @@ output queue, the other new vertical content can be processed. At any point you can force the current queue of horizontal content (the node queue) to be shaped into lines and added to the vertical output queue by calling the function \code{SILE.typesetter:leaveHmode()}. This is handy when for writing custom -functions, but it is a fairly low level control. (Tt is unlikely to be +functions, but it is a fairly low level control. (It is unlikely to be useful while writing a document.) A related but higher level command, \code{\\par}, is more frequently used when writing a document and embedded in the content. The \code{\\par} command first calls diff --git a/documentation/c10-classdesign.sil b/documentation/c10-classdesign.sil index b6e62786f..908a5c236 100644 --- a/documentation/c10-classdesign.sil +++ b/documentation/c10-classdesign.sil @@ -247,7 +247,7 @@ The other way is to export functions that get added to the class itself and can For examples check out the \code{tableofcontents} package for the hooks it sets, but also the \autodoc:command{\tocentry} command it registers that gets called manually in the \code{book} class. -Let’s demonstrate roughly how the \code{tableofcontents} package works. +Let’s demonstrate roughly how the \autodoc:package{tableofcontents} package works. We’ll be using the \code{infonodes} package to collect the information about which pages contain table of content items. First, we set up our infonodes by creating a command that can be called by sectioning commands. diff --git a/documentation/c11-xmlproc.sil b/documentation/c11-xmlproc.sil index 16982a158..c879c95a9 100644 --- a/documentation/c11-xmlproc.sil +++ b/documentation/c11-xmlproc.sil @@ -13,10 +13,10 @@ In addition, options such as paper size could be set; for example, \code{-O pape The class initalization for DocBoox isn’t too fancy; it just loads up a couple packages that will get used later. \begin{note} -Much of the example code in this chapter is in SILE format using macros. +Much of the example code in this chapter is in SIL format using macros. The actual \code{docbook} class currently uses Lua functions to specify these commands. The functionality is the same, but the Lua syntax is more flexible and recommended for most use cases. -The SILE \code{\\define} macros shown here can still be used in a preamble file if desired. +The SILE \autodoc:command{\define} macros shown here can still be used in a preamble file if desired. \end{note} Now we can start defining SILE commands to render XML elements. diff --git a/documentation/c12-tricks.sil b/documentation/c12-tricks.sil index 155d0ff4a..3f47bd41b 100644 --- a/documentation/c12-tricks.sil +++ b/documentation/c12-tricks.sil @@ -164,7 +164,7 @@ end At the end of the document, we will use the emergency \code{chuck} method. Where \code{leaveHmode} means “call the page builder and see there’s enough material to build a page,” \code{chuck} -means “you must get rid of everything on your queue \em{now.”} We add some infinitely +means “you must get rid of everything on your queue \em{now}.” We add some infinitely tall glue to the other typesetter’s queue to help the process along: \begin{verbatim} @@ -385,7 +385,7 @@ end on the default typesetter. If we wanted to make things cleaner, we could swap typesetters by assigning \code{discovery.innerTypesetter} to \code{SILE.typesetter} and then calling ordinary commands, rather than doing the settings and glue -insertion “by hand.”} +insertion “by hand”.} In the future it may make sense for there to be a standard \code{sidenotes} package in SILE, but it has been instructive to see a couple of “non-standard” diff --git a/packages/date/init.lua b/packages/date/init.lua index df819499d..7e9afd5c1 100644 --- a/packages/date/init.lua +++ b/packages/date/init.lua @@ -32,7 +32,8 @@ end package.documentation = [[ \begin{document} -The \autodoc:package{date} package provides the \autodoc:command{\date} command, which simply outputs the current date using the system’s date function. +The \autodoc:package{date} package provides the \autodoc:command{\date} command, which simply outputs a date using the system’s date function. +It defaults to the current date and time, but can be used to format any other input time as well using the \autodoc:parameter{time} parameter. You can customize the format by passing the \autodoc:parameter{format} parameter, following the formatting codes in the Lua manual (\url{https://www.lua.org/pil/22.1.html}). \end{document} diff --git a/packages/math/init.lua b/packages/math/init.lua index b7ad7be2a..9f6a50f6d 100644 --- a/packages/math/init.lua +++ b/packages/math/init.lua @@ -180,7 +180,7 @@ Its main difference from the SILE syntax is that \code{\\mycommand\{arg1\}\{arg2 If it’s more convenient, you can use these Unicode characters directly. The symbol shorthands are the same as in the TeX package \href[src=https://www.ctan.org/pkg/unicode-math]{\code{unicode-math}}. -\code{\\\{formula\}} is a shorthand for \code{\\mrow\{formula\}}. +\code{\{formula\}} is a shorthand for \code{\\mrow\{formula\}}. Since parentheses—among other glyphs—stretch vertically to the size of their englobing \code{mrow}, this is useful to typeset parentheses of different sizes on the same line: \begin[type=autodoc:codeblock]{raw} diff --git a/packages/tableofcontents/init.lua b/packages/tableofcontents/init.lua index 98d987a0d..c5aa9b75c 100644 --- a/packages/tableofcontents/init.lua +++ b/packages/tableofcontents/init.lua @@ -230,8 +230,7 @@ At the end of the document another hook function (\code{writeToc}) will write th The next time the document is built, any use of the \autodoc:command{\tableofcontents} (typically near the beginning of a document) will be able to read that index data and output the TOC. Because the toc entry and page data is not available until after rendering the document, the TOC will not render until at least the second pass. -If by chance rendering the TOC itself changes the document pagination (e.g., the TOC spans more than one page) it might be necessary to run SILE three times to get accurate page numbers shown in the TOC. - +If by chance rendering the TOC itself changes the document pagination (e.g., the TOC spans more than one page) it will be necessary to run SILE a third time to get accurate page numbers shown in the TOC. The \autodoc:command{\tableofcontents} command accepts a \autodoc:parameter{depth} option to control the depth of the content added to the table. diff --git a/packages/twoside/init.lua b/packages/twoside/init.lua index b833bcda1..97e4af933 100644 --- a/packages/twoside/init.lua +++ b/packages/twoside/init.lua @@ -144,9 +144,9 @@ If so, it ejects another page to assure content starts on an odd page. The \autodoc:command{\open-spread} is similar but a bit more tailored to use in book layouts. By default, headers and folios will be suppressed automatically on any empty pages ejected, making them blank. It can also accept three parameters. -The \autodoc:parameter{odd} parameter (default \code{false}) can be used to disable the opening page being odd, hence opening an even page spread. -The \autodoc:parameter{double} parameter (default \code{false}) can be used to always output at least one empty even page before the starting an odd page. -The \autodoc:parameter{blank} parameter (default \code{false}) can be used to not suppress headers and folios on otherwise empty pages. +The \autodoc:parameter{odd} parameter (default \code{true}) can be used to disable the opening page being odd, hence opening an even page spread. +The \autodoc:parameter{double} parameter (default \code{true}) can be used to always output at least one empty even page before the starting an odd page. +The \autodoc:parameter{blank} parameter (default \code{true}) can be used to not suppress headers and folios on otherwise empty pages. Lastly the \autodoc:command{\open-spread-eject} command can be overridden to customize the output of blank pages. By default it just runs \autodoc:command{\supereject}, but you could potentially add decorative content or other features in the otherwise empty space.