TUG Unix CD: HTML documentation

[Ulrik Vieth]

Sebastian wrote:

> QUESTION

> i am getting very confused over texmf/source and texmf/doc for .dtx
> files. if you take a package with his
>   x.ins
>   x.dtx
>   sample.tex
>   readme

> what files do you put in which directory in a really nice working TDS?

I usually start by putting all these files as they come from CTAN
into texmf/source/latex/<package>.  Then I procede as follows:

1. Run latex x.ins and move/copy all the files that are produced, 
   i.e. *.{fd,def,cls,clo,sty} and possibly *.tex (but not sample.tex)
   to ../../../tex/latex/<package>

2. Run latex x.dtx to produce the documentation (it usually takes
   several latex runs) and move/copy the resulting *.{dvi,ps} files 
   to ../../../doc/latex/<package>

3. Copy sample.tex, etc. to ../../../doc/latex/<package>.

4. Leave the readme in the source/<package> directory if it just 
   contains release notes and/or installation instructions.  
   Copy the readme to the doc/<package> directory only if it is
   explicitly meant as end user documentation.

The remaining question is whether step 2. should be done using 
a ltxdoc.cfg file containg \OnlyDescription or whether you want
full source documentation (including index and change history).

Cheers, Ulrik.

P.S. Ideally, the source/<package> directory should look the same
after completing the installation as it was when it came from CTAN.