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

[Karl Berry]

    I'm preparating my first package 'lilyglyphs' for CTAN upload.

Too bad your first package is such a complicated one!  No wonder
pkgcontrib.html and other such things didn't answer all your questions.
Let's see what we can do.

    'plain' directory structure and the supplied tds.zip structure.

It is not required to create the .tds.zip.  While I don't like to be
contrary to Robin ... speaking as the person who does most of the
CTAN->TL imports, I advise against it.  Especially when you are at the
point of asking package structure questions.  The user benefit does not
outweigh the complications, it seems to me.

In any case, I'll focus here on the "plain" structure to reside in the
main area of CTAN.  We can talk about tds.zip later if need be.

    I think the plain lilyglyphs.zip to be downloaded from CTAN can have 
    mostly the same structure as the development directory. 

Yes, I think so too.  The key thing is *not* to have the deep TDS
structure, as Robin explained.  The main lilyglyphs.zip should have a
top-level lilyglyphs/ directory, and then the subdirectories (tex/,
doc/, etc.), and that's pretty much it.

    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'm not sure I'd go so far as to say "have to", but unless perhaps they
are terrifically huge, in principle I would have to recommend it.  The
exact sources that create the OTF's you are distributing.  The idea
being that someone who wanted to work on the package would have all of
the ultimate sources that went into it.

    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?

They don't have to be together, but, like Robin, I recommend it.  Thus I
suggest putting them into the same doc/ subdirectory.  In the uploaded
zip:
lilyglyphs/README            (Must be named "README", specifically.)
lilyglyphs/doc/*.{pdf,tex}.  (No "/source/" level.)

    [many small pdfs]
    /tex/latex/lilyglyphs/glyphimages/pdfs

1) Basically, yes.  For CTAN, your zip should have this:
lilyglyphs/tex/pdfs/*.pdf.  For such a large number of files, it only
makes sense to have them in a separate subdir.
(CTAN folks will effectively unpack your uploaded zip to end up in
m/l/c/lilyglyphs/..., and I will import it into TL under (these days)
texmf-dist/{tex/latex,...}/lilyglphs.  But this is not your
responsibility. :)

2) Please ensure the base filenames are unique.  Being in a unique
directory doesn't help with that, unfortunately.  I fear this is going
to be the biggest problem you have.  Inserting lots of files with
generic names like "crotchet.pdf" and "quaver.pdf" sounds bad to me --
other music packages or user documents might well be using them.  I
suggest prefixing them all with lgl- or something.  Ugly and painful,
but have to do something.
    
    but I don't know what to do with the rest.
    /glyphimages/definitions
    /glyphimages/generated_src

Since those are source files not read by TeX, I would put them into a
source/ subdirectory.  Specifically, for the zip:
lilyglyphs/source/definitions
lilyglyphs/source/generated_src

I'm not sure the /glyphimages/ level buys us much here, but doesn't seem
like a big deal either day.

    The package contains a set of Python scripts 

I recommend this, for scripts that the user invokes from the command
line (which I think is what you're talking about): 
lilyglyphs/scripts/*.py

I think scripts not intended for the user to run (deploy.py?) would be
better in:
lilyglyphs/source/scripts/

The script names also need to be unique (since they'll end up in
/usr/bin, eventually).  Again I suggest an ugly prefix like lgl-.
"gen{Image,Glyph}Command" could be anything from anywhere, sorry to say.

Uh oh, I also see lilyglyphs_common.py.  I suspect that is library code
used by the others?  That complicates things even more.  I'll save that
for the next round.

    how should I direct the user (in the manual)
    so he can make use of these scripts?

The manual could say that distros (either OS-level [Debian, etc.] or
TeX-level [TL, MiKTeX]) will make the scripts available in the regular
binary directories.

As for users who install by hand, instead of writing out laborious and
lengthy and error-prone instructions, I suggest advising them to look at
the installation in TL.  (Or simply download our .tar.xz files for
manual installation ... anyway ... another time ...)

    * The package provides a 'shadow' structure of the above /glyphimages

Where is this in your git tree?  Anyway, do you mean something like a
skeleton directory tree?  I suggest making a .zip out of it and
including that file in your tree.  If users can't run unzip
successfully, it's hopeless anyway.
lilyglyphs/doc/usertree-sample.zip

    /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'?

Looks reasonable to me (except the path should be
lilyglyphs/doc/<stuff>, not doc/lilyglyphs).  Subsubdirectories are not
completely verboten or anything, they are just to be used
sparingly and sensibly.

    Does that mean I should simply put the scripts in a /scripts/lilyglpyhs 
    directory 

Yes.  Well, lilyglyphs/scripts.

    and wait for the distribution to create wrapper scripts for it? 
    
We (TL) have to be the ones to create the wrapper scripts, because
there's no way you can even know what all the platforms are at the time
you upload the package.  Among other reasons.

(FYI: What we do is make symlinks for the Unix platforms and use a
generic wrapper (runscript.tlu) for Windows.  But this is nothing you or
your users should care about.)

    And how would I refer to these beforehand?

See above: "in the usual binary directories".  Of course you can explain
that further if you want, but you'll be tending toward explaining the
basic concept of PATH, etc...

    And where do distributions get their files from, the main directory
    or the .tds file?

I don't know what Christian does for MiKTeX.  For TL, I use the .tds.zip
when it exists (I prefer that it doesn't :), unless it is broken and
fixed versions aren't forthcoming.  (There are about a dozen such
packages.)  Anyway, don't worry about it.  In principle, it should not
matter, the results should be the same.  If I get something in the wrong
place, you can always tell me and I can easily fix it.

Hope this helps.  Let us know what remains unclear; I'm sure there is
plenty :).

karl

P.S. Unrelated to the questions, but for the record:

    rf> user's HOMETEXMF tree.

TEXMFHOME.  HOMETEXMF hasn't been used for many years.