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

Staszek Wawrykiewicz staw at gust.org.pl
Wed Feb 11 06:27:18 CET 2004

On Tue, 10 Feb 2004, Sebastian Rahtz wrote:

> Itay Furman wrote:
> >I have noticed that the default installation of the 'acronym' 
> >package in texlive 2003 (texmf/tex/latex/acronym) has only part 
> >of the documentation in texmf/doc/latex/acronym:
> >	acrotest.dvi  acrotest.tex  readme
> >The user guide, acronym.dvi, produced from acronym.dtx
> >is not there.
> >
> thats a function of my automated CTAN -> TeX Live procedure. I dont
> normally create dvi files from .dtx files, and I throw away existing dvi
> files. its not great, but since there is minimal consistency in
> packages, I tend to be fairly brutal.

I can only add that's really hard to guess which part of the package
(as distributed on CTAN; I'd rather say: prepared by the P.T. Author(s))
could be dedicated to doc/ source/ and *running* stuff (tex/...)
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>/
When macros are of general purpose, they should be put in 

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/...
    Note: font or .mp file can serve for any format, even when
    supporting macros are missing.
1b) all input files (and graphics) for the documentation and/or examples
    should go to doc/.../...

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

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/.../
2c) Typical latex package distributed in .dtx (without external
    documention provided) should be processed and resulting .dvi
    should go --> doc/.../
    We cannot assure that .pdf (preferable) output can be produced,
    so if the documentation in such format is not provided by the 
    Author(s), we'd better stay with .dvi. PostScript documents
    could be however converted to pdf with pstodpf.
2d) Sometimes .dtx contains typical font stuff, so goto 1a)
    (Example: yhmath is an evident font package, so should never go
    to source/latex/, rather to source/fonts/yhmath/
    extracted from .dtx: .mf  -> fonts/source/.../yhmath/
    .tfm -> fonts/tfm/...   etc. etc.
    the documentation -> doc/fonts/yhmath/ 
    only .sty -> tex/latex/yhmath/ ).

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.
Please have in mind that we have many hundreds of packages, and only some
of them are prepared (and even beeing updated) in any consistent way.

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)

> as everyone else says, _testing_ is the key.


Staszek Wawrykiewicz
StaW at gust.org.pl

More information about the tex-live mailing list