% \iffalse meta-comment
%
% hypbmsec.dtx
%
% This file is part of the package `hypbmsec' for use with LaTeX2e.
%
% Function: Bookmarks in sectioning commands.
%
% Copyright (C) 1998,1999,2000 Heiko Oberdiek.
%
% This program 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.
%
% Please send error reports and suggestions for improvements to
%   Heiko Oberdiek <oberdiek@ruf.uni-freiburg.de>.
%
%<*dtx>
          \ProvidesFile{hypbmsec.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{hypbmsec}
%<driver>\ProvidesFile{hypbmsec.drv}
% \fi
%         \ProvidesFile{hypbmsec.dtx}
  [2000/03/22 v2.1 Bookmarks in sectioning commands (HO).]
%
% \GetFileInfo{hypbmsec.dtx}
%
% \CheckSum{159}
%
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{holtxdoc}
\begin{document}
   \DocInput{hypbmsec.dtx}
\end{document}
%</driver>
% \fi
%
% \DoNotIndex{\csname,\endcsname,\expandafter,\noexpand,\string}
% \DoNotIndex{\begingroup,\endgroup,\def,\xdef,\long,\let}
% \DoNotIndex{\ifx,\newcommand,\renewcommand}
%
% \newcommand{\type}[1]{\textsf{#1}}
%
% \SetupTitle{hyperref,section,bookmark,pdf,LaTeX}
% \maketitle
%
% \begin{abstract}
%   This package expands the syntax of the sectioning commands. If the
%   argument of the sectioning commands isn't usable as outline entry,
%   a replacement for the bookmarks can be given.
% \end{abstract}
%
% \tableofcontents
%
% \section{Usage}
%
% \subsection{Bookmarks restrictions}\label{sec:restrictions}
%    Outline entries (bookmarks) are written to a file and have
%    to obey the pdf specification.
%    Therefore they have several restrictions:
%    \begin{itemize}
%    \item Bookmarks have to be encoded in PDFDocEncoding^^A
%          \footnote{\Package{hyperref} doesn't support
%            Unicode.}.
%    \item They should only expand to letters and spaces.
%    \item The result of expansion have to be a valid pdf string.
%    \item Stomach commands like \cmd{\relax}, box commands, math,
%          assignments, or definitions aren't allowed.
%    \item Short entries are recommended, which allow a clear view.
%    \end{itemize}
%
% \subsection{\texorpdfstring{\cmd{\texorpdfstring}}{^^A
%    \textbackslash texorpdfstring}}
%    The generic way in package \Package{hyperref} is the use
%    of \cmd{\texorpdfstring}^^A
%    \footnote{In versions of \Package{hyperref} below 6.54 see
%      \cmd{\ifbookmark}.}:
%    \begin{quote}
%\begin{verbatim}
%\section{Pythagoras:
%  \texorpdfstring{$a^2+b^2=c^2}{%
%    a\texttwosuperior\ + b\texttwosuperior\ =
%    c\texttwosuperior}%
%}
%\end{verbatim}
%    \end{quote}
%
% \subsection{Sectioning commands}
%    The package \Package{hyperref} automatically generates
%    bookmarks from the sectioning commands,
%    unless it is suppressed by an option.
%    Commands that structure the text are here called
%    ``sectioning commands'':
%    \begin{quote}
%    \cmd{\part}, \cmd{\chapter},\\
%    \cmd{\section}, \cmd{\subsection}, \cmd{\subsubsection},\\
%    \cmd{\paragraph}, \cmd{\subparagraph}
%    \end{quote}
%
% \subsection{Places\texorpdfstring{ for sectioning strings}{}}
%    \label{sec:places}
%    The argument(s) of these commands are used on several places:
%    \begin{description}
%    \item[\type{text}]
%      The current text without restrictions.
%    \item[\type{toc}]
%      The headlines and the table of contents with the
%      restrictions of ``moving arguments''.
%    \item[\type{out}]
%      The outlines with many restrictions: The outline
%      have to expand to a valid pdf string with PDFDocEncoding
%      (see \ref{sec:restrictions}).
%    \end{description}
%
% \subsection{\texorpdfstring{Solution with o}{O}ptional arguments}
%    If the user wants to use a footnote within a sectioning command,
%    the \LaTeX{} solution is an optional argument:
%    \begin{quote}
%      |\section[Title]{Title\footnote{Footnote text}}|
%    \end{quote}
%    Now |Title| without the footnote is used in the headlines and
%    the table of contents. Also \Package{hyperref} uses it for the
%    bookmarks.
%
%    This package \Package{\filename} offers two possibilities to
%    specify a separate outline entry:
%    \begin{itemize}
%    \item An additional second optional argument in square brackets.
%    \item An additional optional argument in parentheses (in
%          assoziation with a pdf string that is internally surrounded
%          by parentheses, too).
%    \end{itemize}
%    Because \Package{\filename} stores the original meaning of the
%    sectioning commands and uses them again, there should be no
%    problems with packages that redefine the sectioning commands, if
%    these packages doesn't change the syntax.
%
% \subsection{Syntax}
%    The following examples show the syntax of the sectioning
%    commands. For the places the strings appear the abbreviations
%    are used, that are introduced in \ref{sec:places}.
%
% \subsubsection{\texorpdfstring{Star form}{^^A
%    \textbackslash section*\{\}}}
%    The behaviour of the star form isn't changed. The string
%    appears only in the current text:
%    \begin{article}{Syntax}
%    \begin{quote}
%      |\section*{text}|
%    \end{quote}
%    \end{article}
%
% \subsubsection{\texorpdfstring{Without optional arguments}{^^A
%    \textbackslash section\{\}}}
%    The normal case, the string in the mandatory argument is
%    used for all places:
%    \begin{article}{Syntax}
%    \begin{quote}
%      |\section{text, toc, out}|
%    \end{quote}
%    \end{article}
%
% \subsubsection{\texorpdfstring{One optional argument}{^^A
%    \textbackslash section[]\{\}}}
%    Also the form with one optional parameter in square brackets isn't
%    new; for the bookmarks the optional parameter is used:
%    \begin{article}{Syntax}
%    \begin{quote}
%      |\section[toc, out]{text}|
%    \end{quote}
%    \end{article}
%
% \subsubsection{\texorpdfstring{Two optional arguments}{^^A
%    \textbackslash section[][out]\{\}}}\label{sec:two}
%    The second optional parameter in square brackets is introduced
%    by this package to specify an outline entry:
%    \begin{article}{Syntax}
%    \begin{quote}
%      |\section[toc][out]{text}|
%    \end{quote}
%    \end{article}
%
% \subsubsection{\texorpdfstring{Optional argument in parentheses}{^^A
%    \textbackslash section(out)\{\}}}
%    Often the \type{toc} and the \type{text} string would be the same.
%    With the method of the two optional arguments in square brackets
%    (see \ref{sec:two}) this string must be given twice,
%    if the user only wants to specify a different outline entry.
%    Therefore this package offers another possibility:
%    In association with the internal representation in the pdf file
%    an outline entry can be given in parentheses.
%    So the package can easily distinguish between
%    the two forms of optional arguments and the order does not matter:
%    \begin{article}{Syntax}
%    \begin{quote}
%      |\section(out){toc, text}|\\
%      |\section[toc](out){text}|\\
%      |\section(out)[toc]{text}|
%    \end{quote}
%    \end{article}
%
% \subsection{Without \Package{hyperref}}
%    Package \Package{\filename} uses \Package{hyperref} for support of
%    the bookmarks, but this package is not required.
%    If \Package{hyperref} isn't loaded, or
%    is called with a driver that doesn't support bookmarks,
%    package \Package{\filename} shouldn't be removed,
%    because this would lead to
%    a wrong syntax of the sectioning commands.
%    In any cases package \Package{\filename}
%    supports its syntax and ignores the outline entries,
%    if there are no code for bookmarks.
%    So it is possible to write texts,
%    that are processed with several drivers to get different output
%    formats.
%
% \subsection{Protecting parentheses}
%    If the string itself contains parentheses, they have to be hidden
%    from \TeX's argument parsing mechanism.
%    The argument should be surrounded
%    by curly braces:
%    \begin{quote}
%      |\section({outlines(bookmarks)}){text, toc}|
%    \end{quote}
%    With version 6.54 of \Package{hyperref} the other standard method
%    works, too: The closing parenthesis is protected:
%    \begin{quote}
%      |\section(outlines(bookmarks{)}){text, toc}|
%    \end{quote}
%
% \Installation
%
% \StopEventually{}
%
% \section{Implementation}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    Because of redifining the sectioning commands, it is dangerous
%    to reload the package several times.
%    \begin{macrocode}
\@ifundefined{hbs@do}{}{%
  \PackageInfo{hypbmsec}{Package 'hypbmsec' is already loaded}
  \endinput
}
%    \end{macrocode}
%
%    \begin{macro}{\hbs@do}
%    The redefined sectioning commands calls \cmd{\hbs@do}. It does
%    \begin{itemize}
%    \item handle the star case.
%    \item resets the macros that store the entries for the outlines
%          (\cmd{\hbs@bmstring}) and table of contents (\cmd{\hbs@tocstring}).
%    \item store the sectioning command |#1| in \cmd{\hbs@seccmd}
%          for later reuse.
%    \item at last call \cmd{\hbs@checkarg} that scans and interprets the
%          parameters of the redefined sectioning command.
%    \end{itemize}
%    \begin{macrocode}
\def\hbs@do#1{%
  \@ifstar{#1*}{%
    \let\hbs@tocstring\relax
    \let\hbs@bmstring\relax
    \let\hbs@seccmd#1%
    \hbs@checkarg
  }%
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\hbs@checkarg}
%    \cmd{\hbs@checkarg} determines the type of the next argument:
%    \begin{itemize}
%    \item An optional argument in square brackets can be an entry
%          for the table of contents or the bookmarks. It will be
%          read by \cmd{\hbs@getsquare}
%    \item An optional argument in parentheses is an outline entry.
%          This is worked off by \cmd{\hbs@getbookmark}.
%    \item If there are no more optional arguments, \cmd{\hbs@process}
%          reads the mandatory argument and calls the original
%          sectioning commands.
%    \end{itemize}
%    \begin{macrocode}
\def\hbs@checkarg{%
  \@ifnextchar[\hbs@getsquare{%
    \@ifnextchar(\hbs@getbookmark\hbs@process
  }%
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\hbs@getsquare}
%    \cmd{\hbs@getsquare} reads an optional argument in square
%    brackets and determines, if this is an entry for the table
%    of contents or the bookmarks.
%    \begin{macrocode}
\long\def\hbs@getsquare[#1]{%
  \ifx\hbs@tocstring\relax
    \def\hbs@tocstring{#1}%
  \else
    \hbs@bmdef{#1}%
  \fi
  \hbs@checkarg
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\hbs@getbookmark}
%    \cmd{\hbs@getbookmark} reads an outline entry in parentheses.
%    \begin{macrocode}
\def\hbs@getbookmark(#1){%
  \hbs@bmdef{#1}%
  \hbs@checkarg
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\hbs@bmdef}
%    The command \cmd{\hbs@bmdef} save the bookmark entry in
%    parameter |#1| in the macro \cmd{\hbs@bmstring} and catches
%    the case, if the user has given several outline strings.
%    \begin{macrocode}
\def\hbs@bmdef#1{%
  \ifx\hbs@bmstring\relax
    \def\hbs@bmstring{#1}%
  \else
    \PackageError{hypbmsec}{%
      Sectioning command with too many parameters%
    }{%
      You can only give one outline entry.%
    }%
  \fi
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\hbs@process}
%    The parameter |#1| is the mandatory argument of the sectioning
%    commands. \cmd{\hbs@process} calls the original sectioning command
%    stored in \cmd{\hbs@seccmd} with arguments that depend of which
%    optional argument are used previously.
%    \begin{macrocode}
\long\def\hbs@process#1{%
  \ifx\hbs@tocstring\relax
    \ifx\hbs@bmstring\relax
      \hbs@seccmd{#1}%
    \else
      \hbs@seccmd{\texorpdfstring{#1}\hbs@bmstring}%
    \fi
  \else
    \ifx\hbs@bmstring\relax
      \hbs@seccmd[\hbs@tocstring]{#1}%
    \else
      \hbs@seccmd[\texorpdfstring\hbs@tocstring\hbs@bmstring]{#1}%
    \fi
  \fi
}
%    \end{macrocode}
%    \end{macro}
%
%    We have to check, whether package \Package{hyperref} is loaded
%    and have to provide a definition for \cmd{\texorpdfstring}.
%    Because \Package{hyperref} can be loaded after this package,
%    we do the work later (\cmd{\AtBeginDocument}).
%
%    This code only checks versions of \Package{hyperref} that
%    define \cmd{\ifbookmark} (v6.4x until v6.53) or
%    \cmd{\texorpdfstring} (v6.54 and above). Older versions aren't
%    supported.
%    \begin{macrocode}
\AtBeginDocument{%
  \@ifundefined{texorpdfstring}{%
    \@ifundefined{ifbookmark}{%
      \let\texorpdfstring\@firstoftwo
      \@ifpackageloaded{hyperref}{%
        \PackageInfo{hypbmsec}{%
          \ifx\hy@driver\@empty
            Default driver
          \else
            '\hy@driver'
          \fi
          of hyperref not supported,\MessageBreak
          bookmark parameters will be ignored%
        }%
      }{%
        \PackageInfo{hypbmsec}{%
          Package hyperref not loaded,\MessageBreak
          bookmark parameters will be ignored%
        }%
      }%
    }%
    {%
      \newcommand\texorpdfstring[2]{\ifbookmark{#2}{#1}}%
      \PackageWarningNoLine{hypbmsec}{%
        Old hyperref version found,\MessageBreak
        update of hyperref recommended%
      }%
    }%
  }{}%
%    \end{macrocode}
%
%    Other packages are allowed to redefine the sectioning commands,
%    if they does not change the syntax. Therefore the redefinitons
%    of this package should be done after the other packages.
%    \begin{macrocode}
  \let\hbs@part         \part
  \let\hbs@section      \section
  \let\hbs@subsection   \subsection
  \let\hbs@subsubsection\subsubsection
  \let\hbs@paragraph    \paragraph
  \let\hbs@subparagraph \subparagraph
  \renewcommand\part         {\hbs@do\hbs@part}
  \renewcommand\section      {\hbs@do\hbs@section}
  \renewcommand\subsection   {\hbs@do\hbs@subsection}
  \renewcommand\subsubsection{\hbs@do\hbs@subsubsection}
  \renewcommand\paragraph    {\hbs@do\hbs@paragraph}
  \renewcommand\subparagraph {\hbs@do\hbs@subparagraph}
  \begingroup\expandafter\expandafter\expandafter\endgroup
  \expandafter\ifx\csname chapter\endcsname\relax\else
    \let\hbs@chapter    \chapter
    \renewcommand\chapter    {\hbs@do\hbs@chapter}
  \fi
}
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \StartHistory
% \HistVersion{1998/11/20 v1.0}
%   \begin{itemize}
%   \item First version.
%   \item It merges package \Package{hysecopt} and
%         package \Package{hypbmpar}.
%   \item Published for the DANTE'99 meating^^A
%\URL{}{http://dante99.cs.uni-dortmund.de/handouts/oberdiek/hypbmsec.sty}.
%   \end{itemize}
% \HistVersion{1999/04/12 v2.0}
%   \begin{itemize}
%   \item Adaptation to \Package{hyperref} version 6.54.
%   \item Documentation in dtx format.
%   \item Copyright: LPPL (\CTAN{macros/latex/base/lppl.txt})
%   \item First CTAN release.
%   \end{itemize}
% \HistVersion{2000/03/22 v2.1}
%   \begin{itemize}
%   \item Bug fix in redefinition of \cmd{\chapter}.
%   \item Copyright: LPPL 1.2
%   \end{itemize}
%
% \hfuzz10pt
% \PrintIndex
%
% \Finale
\endinput