Lua files as examples
eduardoochs at gmail.com
Fri Jul 19 13:20:31 CEST 2019
I am also working on a package that has several Lua files and that I
want to submit to CTAN at some point - in some months, I think...
I have a suggestion: add compilation - i.e., lualatex-ing -
instructions that let people test your package quickly. I did that
and my number of users exploded! It went from 1 to 5 if I take "users"
in a strict sense.
Eduardo Ochs =)
On Fri, 19 Jul 2019 at 06:13, Urs Liska <lists at openlilylib.org> wrote:
> 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
> |- luatemplates.sty
> |- luatemplates.lua
> |- documentation
> |- luatemplates.tex (the manual)
> |- luatemplates-manual-templates.lua (required as Lua module by the
> |- 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. 
> > 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
> |- luatemplates.lua
> |- luatemplates
> |- builtins.lua
> |- formatter.lua
> |- ...
> So from within luatemplates.lua I can successfully write
> This does not seem to be related to the current working directory because
> it also works when compiling the manual from the "documentation"
> 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!
> 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:
> > (*) It is possible to use kpsewhich --subdir=yourpkg to filter the
> > extraneous matches, which I implemented years ago for Heiko, but from a
> > quick grep, I didn't see anything actually using it ...
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the tex-live