Lua files as examples

[Eduardo Ochs]

Hi Urs,

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
here

  http://angg.twu.net/dednat6.html#quick-start
  http://angg.twu.net/dednat6/demo-minimal.tex.html
  http://angg.twu.net/dednat6/demo-minimal.tex

and my number of users exploded! It went from 1 to 5 if I take "users"
in a strict sense.

  Cheers,
    Eduardo Ochs =)
    http://angg.twu.net/dednat6.html
    http://angg.twu.net/math-b.html

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
>
> <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 ...
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://tug.org/pipermail/tex-live/attachments/20190719/2173dd6d/attachment.html>