TUG Unix CD: HTML documentation

Joachim Schrod TWG-TDS@SHSU.edu
Mon, 26 Feb 1996 14:53:42 +0100

>>>>> "UV" == Ulrik Vieth <vieth@thphy.uni-duesseldorf.de> writes:

UV> Sebastian wrote:

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

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

I do almost the same, but would like to add my changes, FYI,

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

Use tex-it for getting fully TeXed documents, a script posted
infrequently by me. I append it below.

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

Yes. For my convenience, I have globally installed the following

================ snip snap ========================================
% ltxdoc.cfg					11 Jan 95

% Configuration for LaTeX standard class `ltxdoc'
% (Program documentation for LaTeX)

% A4 paper is used almost everywhere, except in the US; make that the
% default.


% If a file `OnlyDesc' exists in the input path, we just typeset the
% description (i.e., everything until \StopEventually). That's a
% convenient way to get only the user documentation from style files
% that use the ltxdoc class for documentation.


================ snip snap ========================================

i.e., if a file `OnlyDesc' exists in the current directory, only the
description of a .dtx files is typeset. That allows me to `touch
OnlyDesc' instead of creating a package specific ltxdoc.cfg that would
override my global one.

And here is tex-it:
================ snip snap ========================================
# $ITI: tex-it,v 1.3 1995/06/14 10:49:12 schrod Exp $

# tex-it  ---  transform a TeX document to a final DVI file
# (history at end)

#	tex-it [-bi] tex-cmd file
# tex-it runs 'tex-cmd' on 'file' as often as necessary to produce a
# DVI file where all cross references are resolved. That convergence
# is reached by analyzing auxilliary files:
#  -- If file.toc has changed, the table of contents is not up to date.
#  -- If file.idx has changed, the index is not up to date.
#     MakeIndex is assumed to be used for creating the index.
#  -- If file.aux has changed, cross references are not up to date.
#  -- If file.aux contains a "\bibdata" tag and if the set of
#     "\citation" tags have changed, then BibTeX is run.
# No other auxilliary files are handled. No subdocuments (via
# "\include") are supported.
# 'tex-cmd' may be more than one word.
#   `-b'	skip test for BibTeX
#   `-i'	skip test for MakeIndex

# NOTE: On HP-UX this script is not functional, you have to substitute
# /bin/sh by /bin/ksh in the first line. (/bin/sh doesn't have the
# getopts builtin.)

cmd=`basename $0`
	echo "usage: $cmd [-bi] tex-cmd file" >&2
	exit 1

# Normalize and check arguments.

while getopts 'bi' option
   do	case "$option" in
	    b)	do_bibtex=''
	    i)	do_makeindex=''
	    *)	usage

shift `expr $OPTIND - 1`
test $# -gt 0  ||  usage

# Get file name (last argument), discard extension if necessary.

file=`eval "echo \\$$#"`
file=`echo $file | sed 's/\.[^.]*//'`

# Create temporary directory for auxilliary files to compare. Discard
# that directory if the script is terminated. Note that trap handler
# for 0 is executed at the end of the trap handler for the other
# signals.

trap "/bin/rm -rf $tmp" 0
trap "exit 4" 1 2 3 15
mkdir $tmp

# ------------------------------------------------------------
# Set up functions that save auxilliary information and check if they
# have changed. Save functions are called `save_<type>', check
# functions are called `check_<type>'. Check functions set $run_tex to
# "true" if TeX must be run anew. Check functions may run programs to
# create other auxilliary files.

# aux: table of contents & cross references
# We don't check for *.toc files. LaTeX stores the information in the
# AUX file anyhow, and plain-based macros typically produce the table
# of contents at the end of the document, when it's guaranteed to be
# OK.

	if [ -f "$file.aux" ]
	   then	cp "$file.aux" $tmp
	   else	touch "$tmp/$file.aux"

	test -f "$file.aux"  ||  return 0
	cmp -s "$file.aux" "$tmp/$file.aux"  ||  run_tex=true

# bibtex: Citations

	if [ -f "$file.aux" ]
	   then	egrep '^\\(citation|bibdata)' "$file.aux"  |
			sort >"$tmp/$file.bib"
	   else	touch "$tmp/$file.bib"

	test "$do_bibtex" -a -f "$file.aux"  ||  return 0
	egrep '^\\(citation|bibdata)' "$file.aux"  |  sort >$tmp/bib.new
	if grep '^\\bibdata' $tmp/bib.new >/dev/null
	   then	if cmp -s "$tmp/$file.bib" $tmp/bib.new
		   then	: do nothing
		   else	bibtex "$file"

# idx: raw index data

	if [ -f "$file.idx" ]
	   then	cp "$file.idx" $tmp
	   else	touch "$tmp/$file.idx"

	test "$do_makeindex" -a -f "$file.idx"  ||  return 0
	if cmp -s "$file.idx" "$tmp/$file.idx"
	   then	: do nothing
	   else	makeindex "$file"

# Two functions that collect the functions above.



# Process the document by TeX. Determine if TeX must be run anew by
# the functions realized above.

while [ "$run_tex" ]
   do	save_aux_info

# $ITIlog: tex-it,v $
# Revision 1.3  1995/06/14  10:49:12  schrod
#     HP-UX /bin/sh doesn't grok getopts, use ksh instead.
# Revision 1.2  1995/04/19  14:31:06  schrod
#     Support MakeIndex call, too.
# Revision 1.1  1995/03/14  17:07:26  schrod
#     Added script to process a TeX document.
================ snip snap ========================================

Shall I make a package out of this script? (I'll leave for a
conference RSN, where I will be the rest of the week, don't expect
stuff from me before the next weekend.)


Joachim Schrod					Email: jschrod@acm.org
Roedermark, Germany
Net & publication consultant