Lua commands in document vs. creating a package

[thinlines]

I was looking through the documentation for a way to define commands with Lua inside a document so I could add options to those commands. I thought there might not be a way to do it, but I stumbled upon the following answer in another discussion:

\begin[papersize=a6]{document}
\use[module=packages.verbatim]
\lua{
local class = SILE.documentState.documentClass
class:registerCommand("my-ugly-verbatim", function (_, content)
  [...]
end)
}
[...]

Originally posted by @Omikhleia in #1803 (comment)

I could see an argument for why this might not be encouraged. It would probably be better to write a package, but benefits to keeping everything in one file might include portability, for example. I would like to ask everyone what they think about including something about this in the manual.

To encourage package creation, I think that the documentation could be improved to describe the package creation process more clearly. For example, Chapter 10.2 of the manual (p. 101) reads "As well as defining frames and packages, classes may also...", suggesting that package creation has been previously discussed, but isn't (at least not in Chapter 10). Perhaps an additional section or chapter could be added which covers package creation. I wouldn't mind having a go at it, though I haven't written a package before. I did manage to get a custom class working, thanks to the manual and looking through SILE's code. I look forward to feedback on this idea.

N.B. Right now, looking through SILE's code has proven the most effective way for me to figure out how to do what I want to do. Luckily Lua is relatively easy to read, and this is one of SILE's strengths.

[Omikhleia]

Chapter 10 of the manual has been rewritten in #1778 and this will go in the next release -- now addressing both package and class creation with much more details. So you may check it: I think it addresses your concern here? Of course it could still be further improved.

Also note that other chapters are also being revised too (#1794, #1805).

The \lua command is described briefly too in the manual, but I am not sure we should spent time explaining how to implement commands in a document as done above -- It shouldn't indeed be encouraged, IMHO.

[alerque]

Adding a few ad-hoc document specific commands inline to the document where they are relevant isn't something we should discourage. It's a bad workflow if you're doing the same thing in many documents, but it's perfectly reasonable for some odd job.

Right now off the top of my head here are three ways to do it are:

1. Use SILE.registerCommand() and ignore the warning about it being deprecated.

2. Use the document class hack above to just stuff a command into the current class scope.

3. Make a full package in Lua and return it inline. This is basically just the same as taking a stand alone package file and bundling it inline in your document:

   \begin{lua}
   local package = pl.class(require("packages.base"))
   package._name = "mydocumenthacks"
   function package:registerCommands ()
     self:registerCommand("my-ugly-verbatim", function (_, content)
       ...
     end)
   return package
   \end{lua}
   

[thinlines]

Chapter 10 of the manual has been rewritten ... So you may check it: I think it addresses your concern here?

Thank you for letting me know! I should have done a better search before opening an issue. I read through the diff, and I think that it's a great improvement. I would add that perhaps in the part about adding options to classes it might be helpful to new users to use a more concrete example — say for example an implementation of an option allowing the user to switch between (a) unindented paragraphs with space between them and (b) indented paragraphs with no space between them. This is something I regularly use a pair of \set commands in my documents for. Of course there are other ways this could be accomplished, e.g. by defining a command.

[implementing commands in a document as done above] shouldn't indeed be encouraged, IMHO.

I think that the enterprising SILE user should find alerque's comment above very helpful, and I agree that it doesn't need to be in the manual. However, is there a place where users can gather snippets, tips, and tricks such as this one all in one place?

Thanks, alerque, for the comment on different ways to do this.

[Omikhleia]

However, is there a place where users can gather snippets, tips, and tricks such as this one all in one place?

The Wiki maybe?

[Omikhleia]

To encourage package creation, I think that the documentation could be improved to describe the package creation process more clearly. For example, Chapter 10.2 of the manual (p. 101) reads "As well as defining frames and packages, classes may also...", suggesting that package creation has been previously discussed, but isn't (at least not in Chapter 10). Perhaps an additional section or chapter could be added which covers package creation.

For the record, as already mentioned above, since v0.14.10 (#1778) in July 2023:

• The above-mentioned section on classes ("As well as defining frames and packages, classes...") is in §10.2.5
• The package creation process is covered in §10.1

On the other topic raised in this issue, i.e. commands in SIL documents:

• The requester @thinlines recognized that he "could see an argument for why this might not be encouraged", and later that "it doesn't need to be in the manual"
• @alerque too stated that "it's a bad workflow if you're doing the same thing in many documents"
• I suggested the Wiki for code snippets etc., but no contributions were received there... (That's just a statement of facts).
• On "benefits to keeping everything in one file might include portability," I am not really convinced. Portability of such "hacks" in uncertain. Moreover, it blurs the distinction between content and scripting, and it thus lacks a clear separation of concerns. As I wrote elsewhere:

  I am not saying that mixing scripting, layout decisions, styling, and content is inherently bad. I am doing it casually in (documents) (...). But for most content, it’s not the best approach.

Hence, re-reading this issue one year later, it does not seem to me there's anything left to address.

(It was opened further to my own answer in a comment #1803 (comment) -- using a quick and dirty hack for demonstrating something, but it should not be generalized or encouraged.)

I am therefore closing/rejecting this issue.

Thanks for your contribution to the discussion.
Of course, if recent versions of the SILE manual would still need improvements in these areas, please feel free to open a dedicated issue and/or PR.