[tex-live] Re: tex *live* packages [was: .. acronym package missing doc]

[Itay Furman]

On Wed, 11 Feb 2004, Sebastian Rahtz wrote:

> 
> 
> Staszek Wawrykiewicz wrote:
> 
> > Since there are no strict guidelines how to distribute/prepare
> > a package (and so many are rather old, not maintained, but still
> > usable, who knows?), I prepared my own draft notes how we can proceed.
> > 
> > 1. the simplest contents of the package: 
> > README (or similar readme.txt, etc.) -> doc/<format>/<pkgname>/
> > .sty (.tex) -> tex/<format>/<pkgname>/
> thats ok
> 
> > When macros are of general purpose, they should be put in 
> > tex/generic/.../
> 
> and how do you tell they are general purpose?
> 
> > 1a) If the main contents of the package is font or mp stuff,
> >     the documentation goes to doc/font/... or doc/metapost/...
> >     *even* when accompanied with latex's .sty files (which goes
> >     to tex/latex/...
> you'd have to quantify "main contents", and provide an 
> algorithm for calculating it...
> 
> > 1b) all input files (and graphics) for the documentation and/or examples
> >     should go to doc/.../...
> if one can determine what they are
> 
> > 2. the package consists of .dtx, .ins (and README):
> >    such stuff goes to source/.../<pkgname>/
> >    but needs preparation for beeing "live":
> >    .sty, .def, .fd -> tex/latex/.../
> >    .tex examples -> doc/.../
> 
> thats what I do OK at the moment. unless there multiple .ins 
> files, of course.
>

Or more than 'latex file.ins' is required, for example, in 
acronym.ins:

[snip]

\Msg{* To produce the documentation run the file `acronym.dtx'}
\Msg{* through LaTeX.}

[snip]

Of course, I  know nothing about the internals of the production 
of texlive, and my experience is limited to latex. So what I 
propose here might, in fact, be exactly what is done right now; 
or, worthless for any other reason...

Anyway:

The information to produce all package files is embedded in those 
files, sometimes in explicit statements from the contributors as 
in the above example; sometimes implicitly.

One may try the following approach:
1) Extract instructions for producing package files (beyond 
   the 'latex file.ins') from
	readme, README, FILE.ins, FILE.dtx, ...
2) If	none is found
   	or
   If	failed to produce package files according to 1)
   then
   	use current approach

As I see it, the advantage here is that, the extraction engine, 
1) can be built and improved _incrementally_ as more ways in 
which contributors embed instructions are 'discovered' and 
successfully handled by the engine.

If, in addition, submissions to CTAN in the future are going to 
be standardized, then adapting 1) accordingly should be feasible.

In addition, record the way each package was handled in some sort 
of DB to use in following years to speed-up/double-check the 
migration procedure. (Is this what tpm2 for?)


> > 2a) If README (or similar file) contains full description
> >     --> doc/.../
> > 2b) If README (or similar file) contains *only* what to do with .dtx
> >     -- can be left in source/.../
> 
> um, that implies _reading_ the README. sorry, no time for that/
>

The same approach as above might work here, too?
Ambiguous cases handled by symlinking to doc/.../?

> ...
> > 3. Any extra files for pre/postprocessing, etc., not related to the
> >    direct usage and reading/preparing the documentation, should be left
> >    in the source/ area.
> thats my fallback
> 
> > Typical mistakes when using any automata (just to show):
> > a) metaobj as latex package (evident metapost stuff)
> > b) metatex as latex package (plain tex macros)
> 
> my default is latex unless its overridden.
> 
> this is all of course the point of tpm2, to provide all this 
> metadata in a single place.
> 
>