Lua files as examples

[Urs Liska]

18. Juli 2019 23:50, "Karl Berry" <karl at freefriends.org> schrieb:

> Hi Urs - yes, it is no problem to keep the doc .lua files in the doc
> tree.
> 
>> how would I indicate this? 
> 
> The best place to describe intended installation layout is in the README
> file, although assuming the CTAN upload will have (something like)
> doc/luaexamples/*.lua vs. tex/subfolder/*.lua, it will be evident to me
> what to do.

For clarity I'll state that the package is called `luatemplates`.

The structure relevant to the documentation is

<root>
|- luatemplates.sty
|- luatemplates.lua
|- documentation
   |- luatemplates.tex (the manual)
   |- luatemplates-manual-templates.lua (required as Lua module by the manual)
   |- examples
      |- examples-type-one.lua (just listed in the manual)
      |- examples-type-two.lua (listed *and required* in/from the manual)
      |- example*.tex (example files to look at, each having a corresponding .lua file)
|- ..

> 
> Also, what would be the appropriate link
> to point to in the manual (you'll find the example files in ...)?
> 
> It depends on the appropriate subdirectory of doc, e.g.,
> texmf-dist/doc/latex/yourpkgname/luaexamples, but "latex" might be
> "generic" or "support" or whatever. It depends on what your package does :).
> I usually use something corresponding to the main CTAN subtree location.
> (Suggesting something is fine.)

The package is a generic tool for simplifying the development of Lua-based packages, allowing "formatter" templates or functions to be defined in Lua and all the macro and argument handling be done automatically. [1]

> 
> Another thing that can be useful to mention is running "texdoc -l
> yourpkgname", which should show all the relevant files (and maybe some
> irrelevant ones), including the examples.
> 

I didn't know that, sorry. This seems like a good suggestion to give readers an easy way of finding the examples.

> On another front:
> 
>> require(subfolder.module-name) from the main .lua file. 
> 
> Does that actually work? 

I don't really know, that's why I brought it up in this email. It works in my development repository but I know I can't assume the same when put into another context. Probably it works here because everything is found through relative paths.

> Does your script do something to put subfolder
> in the Lua input path, or similar(*)? If not, or even if so, I strongly
> recommend making the file basenames be unique, like
> yourpkg-module-name.lua.

As said, maybe it just works thanks to the relative paths. Another view on the directory structure quoted above is

<root>
|- luatemplates.lua
|- luatemplates
   |- builtins.lua
   |- formatter.lua
   |- ...

So from within luatemplates.lua I can successfully write

    require('luatemplates.builtins')

This does not seem to be related to the current working directory because it also works when compiling the manual from the "documentation" subdirectory.

Your comment made me think of whether this worked because the files are relative to the caller or because they are within the search path. Since changing "require('builtins')" also works I assume it's the latter. In that case I'll rename the files to make them unique so no other users accidentally load them ...
But this should also imply that the files will be found when they are stored in another location not findable through relative paths and independently of the current working directory, right?

> 
> If you have a preference, the runtime .lua files can end up either under
> scripts/ or under tex/. Let me know. --best, karl.

I don't know much about the TDS, but it seems somewhat natural that they are under scripts/.

Thank you for the comments, and your work in general!
Best
Urs

[1]
This is not meant as a request but rather as an invitaion: I would be grateful for any public feedback (and discussiton, and contribution) *before* a CTAN release. The package is located at https://github.com/uliska/luatemplates, where also a compiled PDF of the current manual can be downloaded. I must admit, though, that making it work is a little bit tricky because it requires another package (lyluatex) to be run from its Github repository (instead of TeX Live), and even from a specific branch.

For a glimpse of what it does the following example files may give an idea:
https://github.com/uliska/luatemplates/blob/master/documentation/examples/luatemplates-mwe.tex
and 
https://github.com/uliska/luatemplates/blob/master/documentation/examples/luatemplates-mwe-templates.lua
   or
https://github.com/uliska/luatemplates/blob/master/documentation/examples/validate-options.tex
and
https://github.com/uliska/luatemplates/blob/master/documentation/examples/validate-options.lua
> 
> (*) It is possible to use kpsewhich --subdir=yourpkg to filter the possible
> extraneous matches, which I implemented years ago for Heiko, but from a
> quick grep, I didn't see anything actually using it ...