fix(utilities): Normalize formatting of messages, warnings, and errors

Author: alerque

classes/base.lua

@@ -122,7 +122,7 @@ function class:declareOptions ()
          if self._legacy then
             self._name = name
          elseif name ~= self._name then
-            SU.error("Cannot change class name after instantiation, derive a new class instead.")
+            SU.error("Cannot change class name after instantiation, derive a new class instead")
          end
       end
       return self._name
@@ -247,10 +247,11 @@ function class:initPackage (pack, options)
       "0.14.0",
       "0.16.0",
       [[
-  This package appears to be a legacy format package. It returns a table
-  and expects SILE to guess about what to do. New packages inherit
-  from the base class and have a constructor function (_init) that
-  automatically handles setup.]]
+         This package appears to be a legacy format package. It returns a table and
+         expects SILE to guess about what to do. New packages inherit from the base
+         class and have a constructor function (_init) that automatically handles
+         setup.
+      ]]
    )
    if type(pack) == "table" then
       if pack.exports then
@@ -391,7 +392,11 @@ function class:registerCommands ()
          self:registerCommand(options["command"], content)
          return
       elseif options.command == "process" then
-         SU.warn("Did you mean to re-definine the `\\process` macro? That probably won't go well.")
+         SU.warn([[
+            Did you mean to re-definine the `\\process` macro?
+
+            That probably won't go well.
+         ]])
       end
       self:registerCommand(options["command"], function (_, inner_content)
          SU.debug("macros", "Processing macro \\" .. options["command"])
@@ -438,7 +443,7 @@ function class:registerCommands ()
    self:registerCommand("comment", function (_, _) end, "Ignores any text within this command's body.")
 
    self:registerCommand("process", function ()
-      SU.error("Encountered unsubstituted \\process.")
+      SU.error("Encountered unsubstituted \\process")
    end, "Within a macro definition, processes the contents of the macro body.")
 
    self:registerCommand("script", function (options, content)
@@ -450,22 +455,21 @@ function class:registerCommands ()
             "0.15.0",
             "0.16.0",
             ([[
-      The \script function has been deprecated. It was overloaded to mean
-      too many different things and more targeted tools were introduced in
-      SILE v0.14.0. To load 3rd party modules designed for use with SILE,
-      replace \script[src=...] with \use[module=...]. To run arbitrary Lua
-      code inline use \lua{}, optionally with a require= parameter to load
-      a (non-SILE) Lua module using the Lua module path or src= to load a
-      file by file path.
+               The \script function has been deprecated. It was overloaded to mean too many
+               different things and more targeted tools were introduced in SILE v0.14.0. To
+               load 3rd party modules designed for use with SILE, replace \script[src=...]
+               with \use[module=...]. To run arbitrary Lua code inline use \lua{}, optionally
+               with a require= parameter to load a (non-SILE) Lua module using the Lua module
+               path or src= to load a file by file path.
 
-      For this use case consider replacing:
+               For this use case consider replacing:
 
-          %s
+               %s
 
-      with:
+               with:
 
-          %s
-      ]]):format(original, suggested)
+               %s
+            ]]):format(original, suggested)
          )
       end
       if SU.ast.hasContent(content) then
@@ -548,9 +552,12 @@ function class:registerCommands ()
             SILE.processString(doc, "lua", nil, packopts)
          else
             if options.src then
-               SU.warn(
-                  "Use of 'src' with \\use is discouraged because some of it's path handling\n  will eventually be deprecated. Use 'module' instead when possible."
-               )
+               SU.warn([[
+                  Use of 'src' with \\use is discouraged.
+
+                  Its path handling  will eventually be deprecated.
+                  Use 'module' instead when possible.
+               ]])
                SILE.processFile(options.src, "lua", packopts)
             else
                local module = SU.required(options, "module", "use")

classes/plain.lua

@@ -78,16 +78,17 @@ function class:registerCommands ()
 
    self:registerCommand("noindent", function (_, content)
       if #SILE.typesetter.state.nodes ~= 0 then
-         SU.warn([[\noindent was called after paragraph content has already been processed.
-
-  This will not result in avoiding the current paragraph being indented.
-  This function must be called before any content belonging to the
-  paragraph is processed. If the intent was to suppress indentation of a
-  following paragraph, first explicitly close the current paragraph. From
-  an input document this is typically done with an empty line between
-  paragraphs, but calling the \par command explicitly or from Lua code
-  running SILE.call("par") will end the current paragraph.
-]])
+         SU.warn([[
+            \noindent was called after paragraph content has already been processed
+
+            This will not result in avoiding the current paragraph being indented. This
+            function must be called before any content belonging to the paragraph is
+            processed. If the intent was to suppress indentation of a following paragraph,
+            first explicitly close the current paragraph. From an input document this is
+            typically done with an empty line between paragraphs, but calling the \par
+            command explicitly or from Lua code running SILE.call("par") will end
+            the current paragraph.
+         ]])
       end
       SILE.settings:set("current.parindent", SILE.types.node.glue())
       SILE.process(content)
@@ -181,14 +182,22 @@ function class:registerCommands ()
 
    self:registerCommand("framebreak", function (_, _)
       if not SILE.typesetter:vmode() then
-         SU.warn("framebreak was not intended to work in horizontal mode. Behavior may change in future versions")
+         SU.warn([[
+            \\framebreak was not intended to work in horizontal mode
+
+            Behavior may change in future versions.
+         ]])
       end
       SILE.call("penalty", { penalty = -10000, vertical = true })
    end, "Requests a frame break (switching to vertical mode if needed)")
 
    self:registerCommand("pagebreak", function (_, _)
       if not SILE.typesetter:vmode() then
-         SU.warn("pagebreak was not intended to work in horizontal mode. Behavior may change in future versions")
+         SU.warn([[
+            \\pagebreak was not intended to work in horizontal mode
+
+            Behavior may change in future versions.
+         ]])
       end
       SILE.call("penalty", { penalty = -20000, vertical = true })
    end, "Requests a non-negotiable page break (switching to vertical mode if needed)")
@@ -263,7 +272,11 @@ function class:registerCommands ()
 
    self:registerCommand("center", function (_, content)
       if #SILE.typesetter.state.nodes ~= 0 then
-         SU.warn("\\center environment started after other nodes in a paragraph, may not center as expected")
+         SU.warn([[
+            \\center environment started after other nodes in a paragraph
+
+            Content may not be centered as expected.
+         ]])
       end
       SILE.settings:temporarily(function ()
          local lskip = SILE.settings:get("document.lskip") or SILE.types.node.glue()
@@ -366,12 +379,13 @@ function class:registerCommands ()
          "0.14.5",
          "0.16.0",
          [[
-  The \quote command has *such* bad output it is being completely
-  deprecated as unsuitable for general purpose use.
-  The pullquote package (\use[module=packages.pullquote]) provides one
-  alternative, and the blockquote environment provides another.
-  But you can also copy and adapt the original source from the plain
-  class if you need to maintain exact output past SILE v0.16.0.]]
+            The \quote command has *such* bad output it is being completely deprecated as
+            unsuitable for general purpose use. The pullquote package
+            (\use[module=packages.pullquote]) provides one alternative, and the blockquote
+            environment provides another. But you can also copy and adapt the original
+            source from the plain class if you need to maintain exact output past
+            SILE v0.16.0.
+         ]]
       )
       SILE.call("smallskip")
       SILE.call("par")
@@ -395,10 +409,11 @@ function class:registerCommands ()
          "0.14.6",
          "0.16.0",
          [[
-  The new list package (\use[module=packages.lists) has much better
-  typography for lists. If you want to maintain the exact output of listitem
-  past SILE v0.16.0 copy the source of \listitem from the plain class into
-  your project.]]
+            The new list package (\use[module=packages.lists) has much better typography
+            for lists. If you want to maintain the exact output of listitem past
+            SILE v0.16.0 copy the source of \listitem from the plain class into your
+            project.
+         ]]
       )
       SILE.call("medskip")
       SILE.typesetter:typeset("• ")
@@ -418,7 +433,11 @@ function class:registerCommands ()
       local hbox, hlist = SILE.typesetter:makeHbox(content)
       SILE.typesetter:pushHbox(hbox)
       if #hlist > 0 then
-         SU.warn("Hbox has migrating content (ignored for now, but likely to break in future versions)")
+         SU.warn([[
+            \\hbox has migrating content
+
+            Ignored for now, but likely to break in future versions.
+         ]])
          -- Ugly shim:
          -- One day we ought to do SILE.typesetter:pushHlist(hlist) here, so as to push
          -- back the migrating contents from within the hbox'ed content.

core/cli.lua

@@ -64,10 +64,11 @@ cli.parseArguments = function ()
          end
       end)
       if not has_input_filename and not opts.output then
-         SU.error(
-            "Unable to derive an output filename (perhaps because input is a STDIO stream).\n"
-               .. "  Please use --output to set one explicitly."
-         )
+         SU.error([[
+            Unable to derive an output filename (perhaps because input is a STDIO stream)
+
+            Please use --output to set one explicitly.
+         ]])
       end
       SILE.input.filenames = opts.INPUTS
    end

core/deprecations.lua

@@ -5,11 +5,13 @@ local nostd = function ()
       "0.13.0",
       "0.14.0",
       [[
-  Lua stdlib (std.*) is no longer provided by SILE, you may use
-      local std = require("std")
-  in your project directly if needed. Note you may need to install the Lua
-  rock as well since it no longer ships as a dependency.]]
-   )
+         Lua stdlib (std.*) is no longer provided by SILE. You may use
+
+           local std = require("std")
+
+         in your project directly if needed. Note you may need to install the Lua rock
+         as well since it no longer ships as a dependency.
+      ]])
 end
 -- luacheck: push ignore std
 ---@diagnostic disable: lowercase-global
@@ -31,12 +33,12 @@ local fluentglobal = function ()
       "0.14.0",
       "0.15.0",
       [[
-  The SILE.fluent object was never more than just an instance of a
-  third party library with no relation the scope of the SILE object.
-  This was even confusing me and marking it awkward to work on
-  SILE-as-a-library. Making it a provided global clarifies whot it
-  is and is not. Maybe someday we'll actually make a wrapper that
-  tracks the state of the document language.]]
+         The SILE.fluent object was never more than just an instance of a third party
+         library with no relation the scope of the SILE object. This was even confusing
+         me and marking it awkward to work on SILE-as-a-library. Making it a provided
+         global clarifies whot it is and is not. Maybe someday we'll actually make a
+         wrapper that tracks the state of the document language.
+      ]]
    )
    fluent_once = true
 end
@@ -52,8 +54,9 @@ local nobaseclass = function ()
       "0.13.0",
       "0.14.0",
       [[
-  The inheritance system for SILE classes has been refactored using a different
-  object model.]]
+         The inheritance system for SILE classes has been refactored using a different
+         object model.
+      ]]
    )
 end
 SILE.baseClass = setmetatable({}, {
@@ -89,13 +92,13 @@ local usetypes = function (type)
       "0.15.0",
       "0.16.0",
       ([[
-  In order to keep things tidy internally, more easily allow 3rd party
-  packages to override core functions, and substitute some slow bits
-  with Rust modules, internal types have been moved from the top level
-  SILE global to a types namespace.
+         In order to keep things tidy internally, more easily allow 3rd party packages
+         to override core functions, and substitute some slow bits with Rust modules,
+         internal types have been moved from the top level SILE global to a types
+         namespace.
 
-  Please substitute 'SILE.%s()' with 'SILE.types.%s()'.
-  ]]):format(type, type)
+         Please substitute 'SILE.%s()' with 'SILE.types.%s()'.
+      ]]):format(type, type)
    )
    return SILE.types[type]
 end
@@ -134,13 +137,13 @@ local usetypes2 = function (old, new, type)
       "0.15.0",
       "0.16.0",
       ([[
-  In order to keep things tidy internally, more easily allow 3rd party
-  packages to override core functions, and substitute some slow bits
-  with Rust modules, internal types have been moved from the top level
-  SILE global to a types namespace.
+         In order to keep things tidy internally, more easily allow 3rd party packages
+         to override core functions, and substitute some slow bits with Rust modules,
+         internal types have been moved from the top level SILE global to a types
+         namespace.
 
-  Please substitute 'SILE.%s.%s()' with 'SILE.types.%s.%s()'.
-  ]]):format(old, type, new, type)
+         Please substitute 'SILE.%s.%s()' with 'SILE.types.%s.%s()'.
+      ]]):format(old, type, new, type)
    )
    return SILE.types[new][type]
 end
@@ -174,7 +177,7 @@ function SILE.doTexlike (doc)
       "SILE.processString",
       "0.14.0",
       "0.16.0",
-      [[Add format argument "sil" to skip content detection and assume SIL input]]
+      [[Add format argument "sil" to skip content detection and assume SIL input.]]
    )
    return SILE.processString(doc, "sil")
 end
@@ -186,14 +189,14 @@ local nopackagemanager = function ()
       "0.13.2",
       "0.15.0",
       [[
-  The built in SILE package manager has been completely deprecated. In its place
-    SILE can now load classes, packages, and other resources installed via
-    LuaRocks. Any SILE package may be published on LuaRocks.org or any private
-    repository. Rocks may be installed to the host system root filesystem, a user
-    directory, or a custom location. Please see the SILE manual for usage
-    instructions. Package authors especially can review the template repository
-    on GitHub for how to create a package.
-  ]]
+         The built in SILE package manager has been completely deprecated. In its place
+         SILE can now load classes, packages, and other resources installed via
+         LuaRocks. Any SILE package may be published on LuaRocks.org or any private
+         repository. Rocks may be installed to the host system root filesystem, a user
+         directory, or a custom location. Please see the SILE manual for usage
+         instructions. Package authors especially can review the template repository
+         on GitHub for how to create a package.
+      ]]
    )
 end
 

core/font.lua

@@ -44,7 +44,7 @@ SILE.registerCommand("font", function (options, content)
       if options.language ~= "und" and icu and icu.canonicalize_language then
          local newlang = icu.canonicalize_language(options.language)
          -- if newlang ~= options.language then
-         -- SU.warn("Language '"..options.language.."' not canonical, '"..newlang.."' will be used instead.")
+         -- SU.warn("Language '"..options.language.."' not canonical, '"..newlang.."' will be used instead")
          -- end
          options.language = newlang
       end

core/opentype-parser.lua

@@ -427,7 +427,7 @@ local parseDeviceTable = function (offset, fd)
    elseif header.deltaFormat == 0x0003 then
       buf = vstruct.read("> " .. math.ceil(size / 2) .. "*[2| i8 i8 ]", fd)
    else
-      SU.warn("DeltaFormat " .. header.deltaFormat .. " in Device Table is not supported. Ignore the table.")
+      SU.warn("DeltaFormat " .. header.deltaFormat .. " in Device Table is not supported; ignore the table")
       return nil
    end
    local deviceTable = {}

core/papersize.lua

@@ -79,9 +79,12 @@ setmetatable(papersize, {
          return geometry
       end
       SU.error(string.format(
-         [[Unable to parse papersize '%s'.
-  Custom sizes may be entered with 'papersize=<measurement> x <measurement>'.
-  Predefined paper sizes include: %s]],
+         [[
+            Unable to parse papersize '%s'
+
+            Custom sizes may be entered with 'papersize=<measurement> x <measurement>'.
+            Predefined paper sizes include: %s
+         ]],
          size,
          table.concat(pl.tablex.keys(papersize), ", ")
       ))