[tex-live] Package preparation question (directory structure)

[Robin Fairbairns]

Urs Liska <ul at openlilylib.org> wrote:

>      Hello TeXLive
>       community,

(note that you could have sent to ctan at dante.de)

>       I'm preparating my first package 'lilyglyphs' for CTAN upload. It
>       makes notational elements from LilyPond (<a
>         class="moz-txt-link-freetext" href="http://lilypond.org">http://lilypond.org</a>)
>       available for continuous text in Lua-/Xe-LaTeX documents.
>       Unfortunately I have some questions concerning the directory
>       structure which I absolutely didn't manage to find satisfying
>       answers for, not even after asking on tex.stackexchange. And also
>       searching the tex-live archive didn't really make it clear to me.
>       So I'm sorry to use your time but I have to ask a few questions
>       (trying to be as concise as possible).
>       Better now than after a messy upload. I want the package to show
>       up on CTAN and TeXLive as soon as possible of course ...

we appreciate being asked: many uploads are disorganised in the extreme.

note that we do have a page describing preferred layout, at:

  http://tug.org/texlive/pkgcontrib.html

>       The development repository is at: <a
>         class="moz-txt-link-freetext"
>         href="https://github.com/openlilylib/lilyglyphs">https://github.com/openlilylib/lilyglyphs</a>,
>       and I'm going to write a deploy script to move the files in the
>       correct places.
>       The package is rather complex and consists of more than 160 files
>       currently (with that number growing while the package matures).

(i have to admit that i boggle rather at that...  are they all
substantial files, or do they constitute collection of small ones?)

>       First of all I'm not completely clear about the relation between
>       the 'plain' directory structure and the supplied tds.zip
>       structure.

the tds structure files make life easy for people who can't (for whatever
reason) place a package in an existing installation.  (in principle,
this comprises people who can't maintain their installation
independently -- in such installations, new packages need to go into the
user's HOMETEXMF tree.

>       I think the plain lilyglyphs.zip to be downloaded from CTAN can
>       have mostly the same structure as the development directory. But
>       it is of course very different from a TDS. 
>       
>       
>       a) General questions:
>       
>          o Should I write a script that first prepares the whole
>           directory for CTAN and then copies everything needed to a TDS
>           structure?
>           Or should I rather try to make the 'plain' CTAN directory the
>           same as the TDS structure?

please don't do that last.  remember that you needn't supply a tds
structure at all; if the main distribution is in that form, we will
reject it.

>          o documentation
>           Is it better to have the sources and the .pdfs of the
>           documentation (manual and examples) together in
>           /doc/lilyglyphs or do the sources go to
>           /source/lilyglyphs/doc?

put the sources where ever you like; presonally, i prefer docs all in
one directory with their sources.  whatever you do, avoid the temptation
to produce a multilevel tree, with directories whose content is
exclusively other directories....

>          o fonts
>           The package redistributes (unmodified) OpenType font files
>           under the SIL Open Font License (from <a
>             class="moz-txt-link-freetext" href="http://lilypond.org">http://lilypond.org</a>).
>           Do I have to also supply the Metafont sources for these fonts
>           or is it sufficient to supply a link to the original
>           developer's Git repository in the FONTLOG?

i would favour a link to the git repository.

>       b) TDS related questions:
>       
>          o PDFs used by the package
>           The package uses pdf files in its commands.
>           These pdfs are generated from LilyPond source files.
>           The LilyPond source files themselves are generated from
>           definition files.
>           In the development directory I have them organized as
>           /glyphimages
>           /glyphimages/definitions
>           /glyphimages/generated_src
>           /glyphimages/pdfs
>           I don't really know where to put them. I would place the pdfs
>           in
>           /tex/latex/lilyglyphs/glyphimages/pdfs
>           but I don't know what to do with the rest.

if you don't produce a .tds.zip, this issue doesn't matter, to you.
(the tex live management people have a lot of expertise in this area.)

i must admit that my head is spinning a bit with all your details --
they're not clear to me, now, but may become so at a second reading.

>          o scripts
>           The package contains a set of Python scripts that help the
>           user to extend the package
>           (by generating LaTeX commands from template files and/or by
>           processing template files to pdf images and generating LaTeX
>           files)
>           Of course the user will have to be able to execute them (i.e.
>           know where they are and have the rights to have them
>           executable).
>           I don't know what to do about that. If I put them in
>           /source/lilyglyphs/py how should I direct the user (in the
>           manual) so he can make use of these scripts?

put them in a scripts/ subdirectory, and point the user at them, in the
docs.  *don't* set the "executable" bit in files you upload.

>          o The package provides a 'shadow' structure of the above
>           /glyphimages directory.
>           If the user wants to extend the package she should copy that
>           to a location in his private texmf tree and run the scripts in
>           it (a writable location for extending the package).
>           Where could I put that in (as a directory structure or an
>           archive), and how can I refer to that in the manual?

(i'm not sure i understand this.  we don't want shadow directories on
ctan.)

>       Sorry for that long post and number of question.
>         If I had known that I would probably have developed a simple
>         package with a .sty and a manual ;-)

it sounds to me as if we will need to iterate, anyway, but my guess is
that the watchword needs to be "simplicity" (repeated ad lib).