TUG Unix CD: HTML documentation

[Joachim Schrod]

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

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

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
ltxdoc.cfg:

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

\PassOptionsToClass{a4paper}{article}

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

\InputIfFileExists{OnlyDesc}{%
	\AtBeginDocument{\OnlyDescription}%
    }{}


\endinput
================ 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 ========================================
#!/bin/sh
# $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)


# SYNOPSIS
#
#	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.
#
#
# OPTIONS
#   `-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`
usage()
{
	echo "usage: $cmd [-bi] tex-cmd file" >&2
	exit 1
}


# Normalize and check arguments.

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

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.

tmp=/tmp/tex$$
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.

save_aux()
{
	if [ -f "$file.aux" ]
	   then	cp "$file.aux" $tmp
	   else	touch "$tmp/$file.aux"
	fi
}

check_aux()
{
	test -f "$file.aux"  ||  return 0
	cmp -s "$file.aux" "$tmp/$file.aux"  ||  run_tex=true
}


# bibtex: Citations

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


check_bibtex()
{
	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"
			run_tex=true
		fi
	fi
}


# idx: raw index data

save_idx()
{
	if [ -f "$file.idx" ]
	   then	cp "$file.idx" $tmp
	   else	touch "$tmp/$file.idx"
	fi
}

check_idx()
{
	test "$do_makeindex" -a -f "$file.idx"  ||  return 0
	if cmp -s "$file.idx" "$tmp/$file.idx"
	   then	: do nothing
	   else	makeindex "$file"
		run_tex=true
	fi
}


# Two functions that collect the functions above.

save_aux_info()
{
	save_aux
	save_bibtex
	save_idx
}

check_aux_info()
{
	check_aux
	check_bibtex
	check_idx
}


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

run_tex=true
while [ "$run_tex" ]
   do	save_aux_info
	"$@"
	run_tex=''
	check_aux_info
   done



#======================================================================
#
# $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.)

Cheers,
	Joachim

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