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

[Urs Liska]

Am 04.09.2013 16:47, schrieb Robin Fairbairns:
> Urs Liska <ul at openlilylib.org> wrote:
>
>>       Hello TeXLive
>>        community,
> (note that you could have sent to ctan at dante.de)
I think my problems start when thinking about how the package would be 
moved to a distribution like TeXLive. Providing a ZIP for CTAN and a 
tds.zip that is intended to be downloaded and extracted to ~/texmf would 
be clear to me.
>
>>        I'm preparating my first package 'lilyglyphs' for CTAN upload.
>> ...
> 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
I've of course read that. But I'm afraid my files are too specific so I 
didn't found complete enlightenment there ;-)
>
>>        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?)

The main bunch of files is a collection of small pdf files. The commands 
of the package include them 'as characters'. And of course each pdf has 
the source file it is generated from. And as the package matures and the 
coverage of symbols will increase the number of these files will 
increase too.
Apart from that I think the number of files is 'normal'.
>>        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.

OK.
And where do distributions get their files from, the main directory or 
the .tds file?
>>    
>>        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.

OK.
>>           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.

That seems natural to me.

> whatever you do, avoid the temptation
> to produce a multilevel tree, with directories whose content is
> exclusively other directories....

I don't really understand that.
I think I would have:
/doc/lilyglyphs
/doc/lilyglyphs/lilyglyphs.tex
/doc/lilyglyphs/lilyglyphs.pdf
/doc/lilyglyphs/... (some more files)
/doc/lilyglyphs/glyphlist.html
/doc/lilyglyphs/glyphlist-resources/ (with a .css and some .pngs in it)
/doc/lilyglyphs/examples/ (with more .tex and .pdf files in it)

It that too 'multilevel'?
>>           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.

OK. Seems natural too, as I have never seen or touched the fonts myself. 
Just using it.
>>        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.

Yes, I know (that's why it is under 'TDS related questions')
> (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.

As said above the package uses the files in /glyphimages/pdfs, so I 
think they have to go to the /tex/latex directory.
The files in 'generated_src are the sources from which the pdfs have 
been generated.
The files in 'definitions' are templates from which first the sources 
and then the pdfs have been generated. They are not necessary to _use_ 
the package but have to be provided of course.
>>           o scripts
>>             ...
> put them in a scripts/ subdirectory,
OK
> and point the user at them, in the
> docs.  *don't* set the "executable" bit in files you upload.

That is, I have to write: "You find the scripts in the 
/scripts/lilyglyphs directory of your TeX installation. Please set the 
executable bit yourself and maybe put that to your search path"?
>>           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.)

Hm. As written above there is this /glyphimages directory structure 
where the pdf files used by the package are located.
The provided scripts are there to extend the package with new 
commands/pdfs. In order to do this I must have write access to that 
directory to let the scripts work. Of course this isn't possible inside 
a TeXLive installation but only in the ~texmf tree.
For this I intend to provide an archive that the user can extract in his 
personal tex tree. I called this 'shadow' because it's a private copy of 
a directory inside the package directory.
I hope this is clearer now.

>
>>        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,

Probably.
Some of the questions have already been resolved, though (thanks!)
> but my guess is
> that the watchword needs to be "simplicity" (repeated ad lib).
I don't think the complexity is the result of confusion (or anything the 
like) but in fact part of the package's concept:
- it uses a big number of binary files and has to provide the sources 
for them.
- it is intended to be extendable by the user, and that affects this 
number of files as well as scripting.
This complexity isn't strictly necessary to _use_ the package, but I 
don't want to strip off the extensibility from the distributed version.
(Of course I could say in the manual: "You can extend the package 
yourself, but for this you will have to get it from the Git repository". 
But I don't want to do that either).

Best
Urs