readme.txt                                           2001/08/27

This file describes the files in directory
  CTAN:macros/latex/contrib/supported/oberdiek/
It contains five packages in dtx format:

* hypbmsec 1999/04/12 v2.0 Bookmarks in sectioning commands.
* pagesel  1999/04/13 v1.1 Selecting shipout pages.
* alphalph 1999/04/13 v1.1 Converting numbers to letters.
* twoopt   1999/04/12 v1.3 Definitions with two optional arguments.
* hypcap   2001/08/27 v1.3 Adjusting anchors of captions.

and ten packages as single files:
* pdfcolmk.sty  2000/09/06 v0.5 PDFtex COLor MarK.
* dvipscol.sty  2000/08/31 v1.0 Fix for dvips.def.
* engord.sty    2000/05/23 v1.0 English ordinal numbers.
* refcount.sty  2000/09/07 v2.0 Converting references to numbers.
* settobox.sty  2000/09/07 v1.1 Getting box sizes.
* epstopdf.sty  2001/02/04 v1.1 Conversion with epstopdf on the fly.
* pdflscape.sty 2001/02/04 v0.2 Landscape pages in PDF.
* ifpdf.sty     2001/07/14 v1.1 Providing \ifpdf.
* chemarr.sty   2001/06/22 v1.1 Chemical reaction arrows.
* pdfcrypt.sty  2001/08/09 v0.6 Setting pdf encryption.

COPYRIGHT, DISCLAIMER, LICENSE
==============================

Copyright (C) 1999-2001 Heiko Oberdiek.

The files listed below may be distributed and/or modified under
the conditions of the LaTeX Project Public License,
either version 1.2 of this license or (at your option)
any later version. The latest version of this license
is in
  http://www.latex-project.org/lppl.txt
and version 1.2 or later is part of all distributions
of LaTeX version 1999/12/01 or later.

FILES
=====
readme.txt:   this file.

hypbmsec.dtx: docstrip archive and documentation source.
hypbmsec.ins: docstrip installation script.
hypbmsec.pdf: documentation.

pagesel.dtx:  docstrip archive and documentation source.
pagesel.ins:  docstrip installation script.
pagesel.pdf:  documentation.

alphalph.dtx: docstrip archive and documentation source.
alphalph.ins: docstrip installation script.
alphalph.sty: package file (for TeX users without docstrip).
alphalph.pdf: documentation.

twoopt.dtx:   docstrip archive and documentation source.
twoopt.ins:   docstrip installation script.
twoopt.pdf:   documentation.

hypcap.dtx:   docstrip archive and documentation source.
hypcap.ins:   docstrip installation script.
hypcap.pdf:   documentation.

holtxdoc.zip: archive with files for generating the documentation:
 * holtxdoc.sty: * common macros for all dtx files
                 * hyperref support
                 * patches, bug fixes
 * hothread.sty  * writes thread informations into the log file.
 * hothread.pl   * perl script that reads the thread informations
                   and updates the pdf file, it is a workaround
                   for bugs in pdfTeX (tested with 0.13b).
!!! Caution !!!
 *  These files are very out of date and I intend
    to update these files in future.
 *  For hypcap.dtx a newer version of holtxdoc.sty is
    needed, but it is not yes released by me.
!!! Caution !!!

And the LaTeX packages, documentation is directly available
in the files:
 * pdfcolmk.sty
 * dvipscol.sty
 * engord.sty
 * refcount.sty
 * settobox.sty
 * epstopdf.sty
 * pdflscape.sty
 * ifpdf.sty
 * chemarr.sty
 * pdfcrypt.sty

REQUIREMENTS
============
All packages are LaTeX2e packages.
alphalph can be used by plain-TeX, too.

SHORT USER INTERFACE
====================
For a longer description see the pdf files or
the package files themselves.

* With package `hypbmsec' bookmark entries can be given in another
  argument of the sectioning commands, e.g.:
    out = outline string, toc = string in table of contents
    \section{toc, out, txt}
    \section[toc, out]{txt}
    \section[toc][out]{txt}
    \section[toc](out){txt}
    \section(out)[toc]{txt}
    \section(out){toc, txt}
  hyperref is required to get the bookmarks, but the syntax work
  without hyperref, too.

* Package `pagesel' selects single pages, page areas, odd, or
  even pages for output.

* Package `alphalph' provides the new expandable commands \alphalph
  \AlphAlph. They are like \number, but the expansion consists of
  lowercase and uppercase letters respectively:
     1..26 = a..z
    27..52 = aa..az
    53..78 = ba..bz
   702,703 = zz, aaa
  So the commands can be used as an replacement for LaTeX's \@alph
  and \@Alph macros.

* Package `twoopt' provides commands to define macros with two
  optional arguments:
  \newcommandtwoopt{\Cmd}[3][DefaultA][DefaultB]{Args: #1, #2, #3}
  \renewcommandtwoopt, \providecommandtwoopt

* Package `hypcap' tries a solution for a problem of package
  `hyperref' with figures: The anchor for the figure caption
  is made in the caption itself. Therefore a link will point to
  the caption, but not to the start of the figure environment.
    Now `hypcap' provides a command \capstart that sets the
  anchor for the next \caption and redefines \caption, so that
  \caption uses the previous anchor. If all figure environments
  contain one \caption, then this can be automated by redefining
  the figure environment to execute \capstart every time at the
  beginning of the environment. Also table environments and
  the star forms are supported.
  See hypcap.pdf for further documentation and use.

* Package `pdfcolmk' tries to fix color problems of pdfTeX
  at page breaks because of a missing color stack.
  Use: \usepackage{pdfcolmk} after \usepackage[pdftex]{color}
  See package file for further documentation.

* Package `dvipscol' tries to fix color stack overflows by
  `dvips' (e-TeX recommended).
  Use with e-TeX: \usepackage{dvipscol}
  Use without e-TeX: \usepackage{dvipscol} and all toplevel
    \color commands should be replaced by \nogroupcolor.
  See package file for further documentation.

* Package `engord' converts numbers to English ordinal
  numbers.
  Use: \engord{<LaTeX counter>}
       \engordnumber{<any TeX number>}
  See package file for further documentation and use.

* Package `refcount' extracts the numbers from references.
  The implementation is more safe than the direct use
  of references as numbers, because they works with packages
  such as `hyperref' that adds additional stuff to the
  references.
  Use: Commands similar to \setcounter and \addtocounter:
         \setcounterref, \addtocounterref,
         \setcounterpageref, \addtocounterpageref
       Arguments: {<LaTeX counter>}{<reference>}
       For expandable contexts:
         \getrefnumber, \getpagerefnumber
       Argument: {<reference>}
  See package file for further documentation and use.

* Package `settobox' defines commands similar to
  LaTeX's \settowidth commands:
    \settoboxwidth, \settoboxheight,
    \settoboxdepth, \settoboxtotalheight
  Arguments: {<LaTeX length>}{<LaTeX box name>}
  See package file for further documentation and use.

* Package `epstopdf' adds support of handling eps images
  to package graphic{s,x} with option `pdftex'.
  If an eps image is detected, `epstopdf' is automatically
  called to convert it to pdf format.
  To get the call of `epstopdf' work, the feature `\write18'
  has to be enabled, for example by command line option:
    pdflatex -shell-escape test.tex
  See package file for further documentation and use.

* Package `pdflscape' adds PDF support to the
  environment `landscape' of package `lscape'
  by setting the page attribute `/Rotate'.
  Both the pdfTeX route and the dvips method
  are supported.
  Use: Load this package instead of `lscape':
    \usepackage{pdflscape}
    \begin{landscape}...\end{landscape}
  See package file for further documentation and use.

* Package `ifpdf' looks for pdfTeX in pdf mode and implements
  and sets the switch \ifpdf. The detection is based on
  \pdfoutput and the package will not change this value.
  It works with plain or LaTeX formats.
  Use: LaTeX: \usepackage{ifpdf}
       plain: \input ifpdf.sty
  The package provides the switch \ifpdf:
    \ifpdf
      ... do things, if pdfTeX is running in pdf mode ...
    \else
      ... other TeX or pdfTeX in dvi mode ...
    \fi
  See package file for further documentation and use.

* Package `chemarr': Very often chemists need a longer
  version of reaction arrows (\rightleftharpoons) with
  the possibility to put text above and below. Analogous
  to amsmath's \xrightarrow and \xleftarrow this package
  provides the macro \xrightleftharpoons.
  Requirements: amsmath
  Use: \usepackage{chemarr}
       \xrightleftharpoons[below]{above}
  See package file for further documentation and use.

* Package `pdfcrypt' allows the setting of pdf encryption
  options for
  * pdfTeX, patched by Ricardo Sanchez Carmenes, or
  * VTeX, version 7.35.
  Use: The options can be set as package options or
  in the command \pdfcryptsetup:
    owner=OwnerPassword
    user=UserPassword
    print, copy, edit, annotate=true, false
    all, none
  The encryption is set at \begin{document} by default,
  but this can be forced for an earlier time by option `set'.
  Example:
    \usepackage[owner=Donald,user=Knuth,print=false]{pdfcrypt}
  See package file for further documentation and use.

INSTALLATION
============
For the packages in docstrip format run:
  tex oberdiek.ins
or for a single docstrip package run:
  tex <package>.ins

Generating the documentation:

  1. latex <package>.dtx
  2. makeindex -rs <package>
  3. latex <package>.dtx
  4. makeindex -rs <package>
  5. latex <package>.dtx
Remarks:
* alphalph needs another cycle of latex/makeindex.
* holtxdoc.sty of holtxdoc.zip is needed (see above).
* For hyperlink support hyperref is required. For other than the
  default drivers use an appropriate hyperref.cfg file.
* pdfTeX users:
  * Thumbnail support is added by package thumbpdf:
      CTAN:macros/pdftex/thumbpdf/
    6. thumbpdf <package>
    7. latex <package>
  * For correct article threads hothread.sty and hothread.pl
    (holtxdoc.zip) are needed to correct bugs in pdfTeX:
    8. hothread <package>

CAUTION: I am sorry, that I did not yet found the time
         for updating the files that are necessary
         to produce the documentation.

AUTHOR
======
Heiko Oberdiek
Email: oberdiek@ruf.uni-freiburg.de

QUESTIONS, SUGGESTED IMPROVEMENTS
=================================

If you have questions, problems, error reports,
improvements, or want to have additional features,
please send them to the author.

Happy TeXing
