path: root/Master/texmf-dist/doc/generic/FAQ-en/faq.sty

% $Id: faq.sty,v 1.140 2014/01/28 18:16:50 rf10 Exp rf10 $
%
% This is the LaTeX package that deals with the eccentricities of mark
% up of the UK TeX FAQ.
%
% uses production LaTeX 2e commands
\NeedsTeXFormat{LaTeX2e}[1994/06/01]% at least!
\ProvidesPackage{faq}[2007/06/08 v2.4 English TeX FAQ macros]

% this package new requires etex
\@ifundefined{eTeXversion}{%
  \PackageError{faq}{This package requires e-TeX}{}%
}{}

%
% something affecting fonts: do we use only freely available fonts
% (i.e., are we going to make the postscript of this publicly
% available?); the config file could change this setting if
% necessary.  things affected herein are the definition of \MP (for
% metapost), which isn't currently doable with free fonts, and
% suppression of boldface versions of the logo fonts.
\newif\ifpublicversion  \publicversiontrue

%
% what fonts are we going to typeset in?
\newif\ifboldmathavail
\InputIfFileExists{faqfont.cfg}% must set \ifboldmathavail if necessary
      {\typeout{FAQ -- loading font configuration file faqfont.cfg}}
      {%
        \RequirePackage[T1]{fontenc}%
        \RequirePackage{lmodern}% for sans fonts
        \RequirePackage{mathptmx}
        \RequirePackage{textcomp}%
        \AtBeginDocument{%
          \let\save@textcurrency\textcurrency
          \def\textcurrency{%
            {%
              \fontfamily{lmr}\selectfont
              \save@textcurrency
            }%
          }%
        }
        \boldmathavailfalse
        \IfFileExists{luximono.sty}%
          {\RequirePackage[scaled=0.85]{luximono}}% not using cmtt-alike
          {\RequirePackage{sub-luximono}}% load whatever
        \DeclareRobustCommand{\$}{\char`\$}% otherwise tries to load tctt....
        \@ifundefined{Dings}{\RequirePackage{pifont}%
          \def\Dings{\nopagebreak{\footnotesize
              \dingline{167}}}%
        }%
        {}%
        \DeclareRobustCommand\acro[1]{##1\@{}}
      }

% debugging (requires etex, like much of this package)
%\tracingifs=1

% suppress bold maths if they're not available
\ifboldmathavail\else\let\boldmath\@empty\fi

%
% true for pdf output
\newif\ifsinglecolumn

\RequirePackage{ifpdf}
\ifpdf
  \PackageInfo{faq}{1-column PDF output\@gobble}
  \expandafter\singlecolumntrue
\else
  \PackageInfo{faq}{2-column DVI output\@gobble}
  \expandafter\singlecolumnfalse
\fi

\ifpdf
  % suppress font list from pdftex
  \RequirePackage{atveryend}
  \AtVeryVeryEnd{\batchmode}
\fi

%
% if we're doing pdf, set up hyperref package and backdoors that avoid
% its sillier byproducts...
\ifpdf
  \@ifundefined{pdfavoidoverfull}{}{\pdfavoidoverfull=1}
  \let\@faq@@url\url
  \urldef\DebianSocialContract\@faq@@url
    {http://www.debian.org/social_contract#guidelines}
  \RequirePackage[pdftex%
             ,colorlinks%
  ,pdftitle=The\ UK\ TeX\ FAQ%
         ,linkcolor=blue%
    ,pdfpagemode=UseNone%
      ,pdfstartview=FitH%
%       ,bookmarks=false%
      ,bookmarksnumbered%
                        ]{hyperref}
  \RequirePackage{pdf14}
  \usepackage{thumbpdf}
  \pdfstringdefDisableCommands{%
    \let\cs\psd@cs
    \def\csx#1{\textbackslash#1}%
    \def\marg#1{\textbraceleft#1\textbraceright}%
    \let\acro\@firstofone
    \let\ProgName\@firstofone
    \let\Package\@firstofone
    \def\meta#1{<#1>}%
    %
    \def\WYSIWYG{WYSIWYG}%
    \def\AMSTeX{AmSTeX}%
    \def\BibTeX{BibTeX}%
    \def\bibtex{BibTeX}%
    \def\PiCTeX{PiCTeX}%
    \def\pictex{PiCTeX}%
    \def\CDROM{CD-ROM}%
    \def\TeXXeT{TeXXeT}%
    \def\MLTeX{ML-TeX}%
    \def\MP{MetaPost}%
    \def\dots{...}%
    \def\obracesymbol{\{}%
    \def\cbracesymbol{\}}%
    \def\,{}%
  }%
  \begingroup
    \lccode`\~=`\|%
  \lowercase{\endgroup
    \def\psd@cs~#1~{\textbackslash#1}%
  }%
  % adding table of contents to bookmarks
  \let\Orig@tableofcontents\tableofcontents
  \def\tableofcontents{%
    \pdfbookmark[1]{\contentsname}{contents}%
    \Orig@tableofcontents
  }%
  % adding \subsection*{Finding the Files}
  \AtBeginDocument{%
    \let\Orig@subsection\subsection
    \def\subsection{%
      \@ifstar{\bookmark@subsectionstar}{\Orig@subsection}%
    }%
  }%
  \def\bookmark@subsectionstar#1{%
    \advance\Hy@linkcounter by 1\relax
    \pdfbookmark[2]{#1}{subsectionstar.\the\Hy@linkcounter}%
    \Orig@subsection*{#1}%
  }%
\fi

%
% general support
%\RequirePackage{calc}
\RequirePackage{microtype}
%
% code for handling logo font
%% \RequirePackage{mflogo}
%% \ifpublicversion
%%   \renewcommand{\MP}{Meta\-Post}
%%   \let\faq@@MF\MF
%%   \def\faq@bx{bx}
%%   \DeclareRobustCommand{\MF}{{%
%%       \ifx\f@series\faq@bx
%%         \expandafter\textmd%
%%       \fi
%%       {\faq@@MF}%
%%     }%
%%   }
%% \fi
\DeclareRobustCommand\MF{Meta\-font}
\let\mf\MF
\DeclareRobustCommand\MP{Meta\-post}
\let\mp\MP
\newcommand\ttype{TrueType}
\newcommand\otype{OpenType}
\let\textlogo\textmd
%
% define substitutes for stupid_names
\newcommand\LaTeXo{\latex\,2.09}
  \newcommand\latexo{\latex\,2.09}
\newcommand\AMSTeX{AMS\TeX}
\newcommand\AMSLaTeX{AMS\latex}
  \newcommand\amslatex{AMS\latex}
\newcommand\BibTeX{Bib\TeX}
  \newcommand\bibtex{Bib\TeX}
\newcommand\PiCTeX{PiC\TeX}
  \newcommand\pictex{PiC\TeX}
  \newcommand\texlive{\TeX{} Live}
% and...
%
% ifthenelse for the undefined references
\RequirePackage{ifthen}
%
% tables are all long'uns
\RequirePackage{booktabs}
%
% we define conditional stuff using Eijkhout's package
\RequirePackage{comment}
\def\CommentCutFile{tmp/comment.cut} % use this in place of ./comment.cut
\excludecomment{htmlversion}
\includecomment{typesetversion}
\ifpdf
  \includecomment{pdfversion}
  \includecomment{wideversion}
  \includecomment{hyperversion}
  \excludecomment{flatversion}
  \excludecomment{dviversion}
  \excludecomment{narrowversion}
\else
  \excludecomment{pdfversion}
  \excludecomment{wideversion}
  \excludecomment{hyperversion}
  \includecomment{flatversion} % non-hyper
  \includecomment{dviversion}
  \includecomment{narrowversion}
\fi
%
% define commands that behave differently according to the above
% \begin{hyperversion}
%   \newcommand\quotify[1]{``#1''}
% \end{hyperversion}
% \begin{flatversion}
%   \let\quotify\@firstofone
% \end{flatversion}
%
% dummy environment for separating the intro
\newenvironment{introduction}{}{}
%
% but we also want short versions, like LaTeX2HTML's
\let\htmlonly\@gobble
\let\nothtml\@firstofone
\let\latexhtml\@firstoftwo
\ifpdf
  \let\narrowonly\@gobble
  \let\wideonly\@firstofone
  \let\hyperflat\@firstoftwo
\else
  \let\narrowonly\@firstofone
  \let\wideonly\@gobble
  \let\hyperflat\@secondoftwo
\fi
\let\hyperonly\wideonly
\let\flatonly\narrowonly
%
% the little bit(s) of code that's(re) going to be ignored when the
% html is generated are enclosed by the following two commands
\let\htmlignore\relax
\let\endhtmlignore\relax

%
% the Baskerville and other logos and abbreviations
\providecommand\BV{\emph{Baskerville}}
\providecommand\DANTE{\acro{DANTE}}
\providecommand\MSDOS{\acro{MS-DOS}}
\providecommand\CDROM{\acro{CD-ROM}}
%
\providecommand\elatex{e-\LaTeX{}}
\providecommand\plaintex{Plain \TeX{}}
\providecommand\miktex{MiKTeX}
\providecommand\texshop{\ProgName{TeXshop}}
\providecommand\texworks{\ProgName{TeXworks}}
%
\newcommand\ctan{\acro{CTAN}}
\newcommand\tex{\TeX{}}
%
\newcommand\macosx{Mac \acro{OS}/X}
%
%% \providecommand\TeXXeT{\TeX-{}-X\lower.5ex\hbox{E}\kern-.1667emT\@}
%\providecommand\MLTeX{ML-\TeX}
%
% provided for consistency's sake
\newcommand\PS{PostScript}
%
% to get \\ into example command arguments
\def\bsbs{\char`\\\char`\\}
%
\def\careof{\leavevmode\hbox{\raise.75ex\hbox{c}\kern-.15em
                /\kern-.125em\smash{\lower.3ex\hbox{o}}}}
%
% another silliness:
\providecommand{\textoslash}{\o}
%
% \cs{SMC} \emph{isn't} small caps~--- Barbara Beeton says she thinks
% of it as ``big small caps''.  She says (modulo capitalisation of
% things\dots):
% \begin{quote}
%   For the things it's used for, regular small caps are not
%   appropriate~--- they're too small.  Real small caps are
%   appropriate for author names (and are so used in continental
%   bibliographies), section headings, running heads, and, on
%   occasion, words to which some emphasis is to be given.  \cs{SMC}
%   was designed to be used for acronyms and all-caps abbreviations,
%   which look terrible in small caps, but nearly as bad in all caps
%   in the regular text size.  The principle of using ``one size
%   smaller'' than the text size is similar to the design of caps in
%   German~--- where they are smaller relative to lowercase than are
%   caps in fonts intended for English, to improve the appearance of
%   regular text in which caps are used at the heads of all nouns, not
%   just at the beginnings of sentences.
% \end{quote}
%
% We define this in terms of the memory of the size currently selected
% that's maintained in \cs{@currsize}: if the user does something
% silly re.~selecting fonts, we'll get the wrong results.  The
% following code is adapted from |relsize.sty| by Donald Arseneau and
% Matt Swift, from a 2.09 original by Bernie Cosell.  (Note that the
% order of examination of \cs{@currsize} is to get the commonest cases
% out of the way first.)
%    \begin{macrocode}
%<!latex2e>\def\SMC{\small}
%<*latex2e>
\DeclareRobustCommand\SMC{%
  \ifx\@currsize\normalsize\small\else
   \ifx\@currsize\small\footnotesize\else
    \ifx\@currsize\footnotesize\scriptsize\else
     \ifx\@currsize\large\normalsize\else
      \ifx\@currsize\Large\large\else
       \ifx\@currsize\LARGE\Large\else
        \ifx\@currsize\scriptsize\tiny\else
         \ifx\@currsize\tiny\tiny\else
          \ifx\@currsize\huge\LARGE\else
           \ifx\@currsize\Huge\huge\else
            \small\SMC@unknown@warning
 \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
}
\newcommand\SMC@unknown@warning{\PackageWarning{faq}{Unknown text font
                                   size command -- using \string\small}}
\DeclareRobustCommand\textSMC[1]{{\SMC #1}}
%    \end{macrocode}
%
% The \cs{acro} command uses \cs{SMC} as it was originally intended.
% Note that, since most of these things are uppercase-only names, it
% fiddles with the spacefactor after inserting its text.  font config
% files may define \cs{acro} otherwise
%
%    \begin{macrocode}
\@ifundefined{acro}{%
  \DeclareRobustCommand\acro[1]{\textSMC{#1}\@}%
}{}
%    \end{macrocode}
%
%\TUGboat (effectively) takes arguments {<empty>}vol(issue)
\DeclareRobustCommand\TUGboat[1]{\expandafter\@TUGboat\ignorespaces}
\def\@TUGboat#1(#2){\textsl{TUGboat} \textbf{#1}(#2)}
%
% The NTS and eTeX (and for consistency Eplain) logos
%% \DeclareRobustCommand\NTS{$\mathcal{N}$\lower.5ex\hbox
%%     {$\mathcal{T}$}$\mathcal{S}$\@}
%% \DeclareRobustCommand\eTeX{{$\varepsilon$}-\TeX}
%% \DeclareRobustCommand\eTeX{e-\TeX}
%% \DeclareRobustCommand\Eplain{Eplain}
%% \DeclareRobustCommand\PDFTeX{\acro{PDF}\TeX}
%% \DeclareRobustCommand\PDFLaTeX{\acro{PDF}\LaTeX}
%% \DeclareRobustCommand\CONTeXT{Con\TeX{}t}
\DeclareRobustCommand\YandY{\acro{Y}\&\acro{Y}}

% non-silly names...
\renewcommand\TeX{TeX}
\newcommand\Eplain{Eplain}
\newcommand\etex{e-\TeX}
\let\eTeX\etex % some day all the old format will have gone...
\newcommand\ExTeX{Ex\TeX}
\newcommand\NTS{NTS}
\newcommand\PDFTeX{PDF\TeX}
\newcommand\pdftex{PDF\TeX}
\newcommand\LuaTeX{Lua\TeX}
\newcommand\luatex{Lua\TeX}
\newcommand\lualatex{Lua\LaTeX}
\newcommand\xetex{XeTeX}
\newcommand\xelatex{XeLaTeX}
%\newcommand\TeXXeT{TeX-{}-XeT}

\newcommand\AllTeX{(La)\TeX}
\newcommand\alltex{(La)\TeX}
\newcommand\CONTeXT{Con\TeX{}t}
\newcommand\context{Con\tex{}t}
\newcommand\PDFLaTeX{PDF\LaTeX}
\newcommand\pdflatex{PDF\latex}
\renewcommand\LaTeX{La\TeX}
\newcommand\latex{La\TeX}
\newcommand\twee{2e}
\renewcommand\LaTeXe{\LaTeX\twee}
\newcommand\latexe{\LaTeX\twee}
%
% Other odds and ends (appear differently in TeX and http or plain
% text
%
% wysiwyg gets capitalised at the beginning of a sentence.  not
% entirely reliably...
\DeclareRobustCommand\WYSIWYG{%
  \ifvmode
    \let\faq@tempa\MakeUppercase
  \else
    \ifnum\spacefactor>2000
      \let\faq@tempa\MakeUppercase
    \else
      \let\faq@tempa\relax
    \fi
  \fi
  \textsc{\faq@tempa wysiwyg}%
}
%
% Command for doing `square one' :-}
\newcommand\sqfbox[1]{\framebox{\makebox[\totalheight]{#1\/}}}
%
% an arrow used as a hyphen...
\newcommand\arrowhyph{\ensuremath{\rightarrow}\penalty0\hskip0pt\relax}
%
% Here's a \fullline macro that works in lists and so on
\newcommand\fullline[1]{\@tempdima\hsize\relax
  \advance\@tempdima-\leftmargin\relax
  \advance\@tempdima-\rightmargin\relax
  \hb@xt@\@tempdima{#1}%
}
%
% list indentations (narrower than default because two-column, but
% squeezed further to gain a bit more space still)
\setlength\leftmargini  {1.8em}
\setlength\leftmarginii {1.2em}
\setlength\leftmarginiii{1em}
\setlength\leftmarginiv {0.8em}
%
% for tidy expression of things with parentheses around them:
\newcommand\parens[1]{(#1)}
\newcommand\oparen{(}%)( [footling around to match brackety things in emacs]
\newcommand\cparen{)}
%
% make the tex logo robust
\edef\@tempa{\noexpand\DeclareRobustCommand\noexpand\TeX{\TeX}}
\@tempa
%
% this piece of fantasy was let loose on an unsuspecting world by
% christina thiele, but i bet she didn't write it ;-)
\edef\diatop{\noexpand\protect\csname diatop \endcsname}
\expandafter\def\csname diatop \endcsname[#1|#2]{%
  \leavevmode
  {%
    \setbox1=\hbox{{#1{}}}\setbox2=\hbox{{#2{}}}%
    \dimen0=\ifdim\wd1>\wd2\wd1\else\wd2\fi%
    \dimen1=\ht2\advance\dimen1by-1ex%
    \setbox1=\hbox to1\dimen0{\hss#1\hss}%
    \rlap{\raise1\dimen1\box1}%
    \hbox to1\dimen0{\hss#2\hss}%
  }%
}%
%
% for han the thanh (who knows whether i've actually got this right; i
% can't use the T5 fonts, which aren't even really publicly available
% yet)
\DeclareRobustCommand{\The}{Th\diatop[\'|\^e]}
%% %
%% % 2e's LaTeX logo sets the A in scripstyle jammed up to the top of the T; it
%% % also has the advantage that it's set in the same font as the
%% % surrounding text.  However, the esteemed bbeeton says the logo looks
%% % "squidge awful" in italic text (I agree; and the same is true of its
%% % behaviour in slanted text)
%% %
%% % So here's a version that allows for the slant of the leading L
%% \DeclareRobustCommand{\LaTeX}{L%
%%         {\setbox0\hbox{T}%
%%          \setbox\@tempboxa\hbox{$\m@th$%
%%                                 \csname S@\f@size\endcsname
%%                                 \fontsize\sf@size\z@
%%                                 \math@fontsfalse\selectfont
%%                                 A}%
%%          \@tempdima\ht0
%%          \advance\@tempdima-\ht\@tempboxa
%%          \@tempdima\strip@pt\fontdimen1\font\@tempdima
%%          \advance\@tempdima-.36em
%%          \kern\@tempdima
%%          \vbox to\ht0{\box\@tempboxa
%%                       \vss}%
%%         }%
%%         \kern-.15em
%%         \TeX}
%% %
%% % Ditto for \AllTeX (as used in TUGboat)
%% \DeclareRobustCommand{\AllTeX}{(L%
%%         {\setbox0\hbox{T}%
%%          \setbox\@tempboxa\hbox{$\m@th$%
%%                                 \csname S@\f@size\endcsname
%%                                 \fontsize\sf@size\z@
%%                                 \math@fontsfalse\selectfont
%%                                 A}%
%%          \@tempdima\ht0
%%          \advance\@tempdima-\ht\@tempboxa
%%          \@tempdima\strip@pt\fontdimen1\font\@tempdima
%%          \advance\@tempdima-.36em
%%          \kern\@tempdima
%%          \vbox to\ht0{\box\@tempboxa
%%                       \vss}%
%%         }\kern-.075em)%
%%         \kern-.075em\TeX}
%% %
%% % A similar game is used in defining an `all LaTeX' sort of thing:
%% \DeclareRobustCommand\twee{2$_{\textstyle\varepsilon}$}
%
% it proves that, for Alan's stuff, the following needs to have been
% done _before_ we define the macros
\RequirePackage{shortvrb}
\MakeShortVerb{\|}
%
% A command which sets some text in typewriter, with the hyphenchar
% temporarily set to its first argument \FAQverb\HYPHEN{TEXT}.
% NB: This requires no catcode hackery, so should work inside moving
% arguments.  It will, however, produce spurious spaces after CSs, and
% won't allow brace-unmatched input.  It also won't survive going into a
% moving argument if \HYPHEN won't.
%
\let\FAQverbFamily\ttfamily
\DeclareRobustCommand{\FAQverb}[2]{{%
    \ifvmode\leavevmode\fi
    \lefthyphenmin=256\setlanguage\language
    \FAQverbFamily\hyphenchar\the\font`#1\relax
    \def\@tempa{#2}%
    \expandafter\@faq@strip\meaning\@tempa\@faq@strip
    \hyphenchar\the\font\m@ne
}\setlanguage\language}
\def\@faq@strip#1->#2\@faq@strip{#2}
%
% Document markup:
%
% (new method, using url.sty -- old version using FAQverb stuff
% deleted from comments 2000/03/24)
\newcommand\Email{\begingroup \urlstyle{tt}\Url}     % email address
\ifpdf
\def\mailto#1{\href{mailto:#1}{\Email{#1}}}
\else
\newcommand\mailto{\begingroup \urlstyle{tt}\Url}    % mailable address
\fi
\DeclareRobustCommand\FTP{\begingroup \urlstyle{tt}\Url} % FTP site address
\DeclareRobustCommand\File{\begingroup \urlstyle{tt}\Url} % File name
\DeclareRobustCommand\@ctan@path{\begingroup \urlstyle{tt}\Url} % CTAN path
                                                     % (argument in braces)
\ifpdf
\newcommand\@CTAN[3]{\href{#1#2#3}{\@ctan@path{#2}}} % relay via hyperreference
\else
\newcommand\@CTAN[3]{\@ctan@path{#2}}                % text-only reference
\fi
\newcommand\Newsgroup{\begingroup \urlstyle{tt}\Url} % newsgroup
\let\URL\url                                         % just a URL
\ifpdf
\let\nolinkURL\nolinkurl                             % unlinked version
\else
\let\nolinkURL\url                                   % there ain't no linking
\fi
% url.sty defines \path, etc.  hyperref may redefine...
\ifpdf
  % hyperref has defined \href
  \let\FAQ@@href\href
  % we actually want to ignore the * in \href*
  \def\href{\@ifstar\FAQ@@href\FAQ@@href}
\else
%
% here, latex for printing
  \newcommand\href{%
    \@ifstar
      {\let\@href@text\@empty\@href@a}%
      {\def\@href@text{see }\@href@a}%
  }
%
% decisions now made about 
  \newcommand\@href@a{\begingroup
    \@makeother\\%
    \@makeother\_%
    \@makeother\%%
    \@makeother\~%
    \@makeother\#%
    \@href@b
  }
%
% enter here in a group with sanitised arg
  \newcommand\@href@b[1]{\endgroup
    \urldef\@href@tempurl\url{#1}%
    \@href@getanchor
  }
%
% out of the group again: argument is the anchor
  \newcommand\@href@getanchor[1]{#1%
    \@ifnextchar@nosp'%
      {\@href@getanchorq}%
      { (\@href@text\@href@tempurl)\@let@token}%
  }
%
% one quote after the anchor - check for a second
  \newcommand\@href@getanchorq{% gobble the first quote
     \@ifnextchar@nosp'%
      \href@getanchor@qq
      {' (\@href@text\@href@tempurl)\@let@token}% restore quote
  }
  \newcommand\href@getanchor@qq{% gobble the second quote too
    {'' (\@href@text\@href@tempurl)}% restore both quotes
  }
%
% two quotes after the anchor
\fi
\long\def\@ifnextchar@nosp#1#2#3{%
  \let\reserved@d=#1%
  \def\reserved@a{#2}%
  \def\reserved@b{#3}%
  \afterassignment\@ifnch@nosp\let\@let@token= }
\def\@ifnch@nosp{%
  \ifstophere\stopherefalse\show\@let@token\fi
  \ifx\@let@token\reserved@d
    \expandafter\reserved@a
  \else
    \expandafter\reserved@b
  \fi
}
\setcounter{errorcontextlines}{999}
\newif\ifstophere

%%\ifx\DeclareUrlCommand\undefined
\DeclareRobustCommand\ProgName{%
  \begingroup
  \def\UrlFont{\rmfamily\itshape}\csname Url@do\endcsname
  \Url
}
\let\progname\ProgName
%%\else
%%  \DeclareUrlCommand\@ProgName{\def\UrlFont{\rmfamily\itshape}}
%%  \DeclareRobustCommand\ProgName{\@ProgName}
%%\fi
\let\Package\ProgName                                      % pro tem
\let\package\Package

\let\Class\Package                                         % ...
\let\class\Class

\let\FontName\Package                                      % ...
% \let\fontname\FontName                                   % ahh, ... no!

% another little oddity (from doc.sty originally, iirc)
\newcommand\meta[1]{\ensuremath{\langle}\emph{#1}\ensuremath{\rangle}}

%
% ISBN references
\def\ISBN{\@ifstar\@ISBNstar\@ISBN}
\def\@ISBNstar#1#2{\acro{ISBN}-10~#1, \acro{ISBN}-13~#2}
\def\@ISBN#1{\acro{ISBN}-10~#1}
%
% Alan's code for CTAN references (now hacked to be capable of urls
% for use in pdf output):
%
% define a location for a package on CTAN
% ignores a leading * (which has meaning for html version only)
% #1 is the package name
% #2 is the CTAN path to the thing
% a package in a directory
\ifpdf
  \newcommand{\CTANdirectory}{\@ifstar\@sCTANdirectory\@CTANdirectory}
\else
  \newcommand{\CTANdirectory}{\@ifstar\@CTANdirectory\@CTANdirectory}
\fi
\newcommand{\@CTANdirectory}[2]{\@ifundefined{ctan-#1}{%
    \expandafter\gdef\csname ctan-#1\endcsname{\@CTAN\LocalCTAN{#2}\CTANDirFmt}%
  }{%
    \PackageWarningNoLine{faq}{Repeated definition of label: #1}%
    \stepcounter{CTAN@replabs}%
  }%
  \@faq@disposeopt
}
\ifpdf
  \newcommand{\@sCTANdirectory}[2]{\@ifundefined{ctan-#1}{%
      \expandafter\gdef\csname ctan-#1\endcsname{\@CTAN\LocalCTAN{#2}/}%
    }{%
      \PackageWarningNoLine{faq}{Repeated definition of label: #1}%
      \stepcounter{CTAN@replabs}%
    }%
    \@faq@disposeopt
  }
\fi
%
% a package in a single file (the same appearance, but the WWW -- and
% ultimately the pdf -- versions are different).
\ifpdf
\newcommand{\CTANfile}[2]{\@ifundefined{ctan-#1}{%
    \expandafter\gdef\csname ctan-#1\endcsname{\@CTAN\LocalCTAN{#2}{}}%
  }{%
    \PackageWarningNoLine{faq}{Repeated definition of label: #1}%
    \stepcounter{CTAN@replabs}%
  }%
  \@faq@disposeopt
}
\else
\let\CTANfile\CTANdirectory
\fi
%
% get rid of optional catalogue pointer in \CTAN(directory|file)
\newcommand\@faq@disposeopt{%
  \@ifnextchar[\@faq@gobbleopt{}% ]
}
\def\@faq@gobbleopt[#1]{}
%
% Make reference to a CTAN package
%
% counters for the undefined references and repeated labels
\newcounter{CTAN@unrefs}
\newcounter{CTAN@replabs}%
%
% the command itself
\newcommand{\CTANref}[1]{%
  \@ifundefined{ctan-#1}{%
    \PackageWarning{CTAN}{Undefined reference: #1}%
    \stepcounter{CTAN@unrefs}%
    \futurelet\@let@token\faq@zap@trailing@opt
  }{%
    \csname ctan-#1\endcsname
    \expandafter\let
      \expandafter\faq@cat@ref\csname ctan-catref-#1\endcsname
  }%
  \futurelet\@let@token\faq@check@trailing@opt
}
\newcommand\faq@check@trailing@opt{%
  \ifx\@let@token[%
    \expandafter\faq@collect@catref
  \else
    \let\faq@catref\@empty%
  \fi
}
\def\faq@collect@catref[#1]{\edef\faq@catref{\noexpand
    \url{\faq@fixed@cataddr#1.html}%
  }%
}%
\def\faq@fixed@cataddr{ help/Catalogue/}%
\newcommand\faq@zap@trailing@opt{\ifx\@let@token[%
  \expandafter\@gobble@opt\fi
}
\def\@gobble@opt[#1]{}
%
% href to a ctan package
\ifpdf
  \DeclareRobustCommand{\CTANhref}[2]{\@ifundefined{ctan-#1}{%
      \PackageWarning{CTAN}{Undefined reference: #1}%
      \stepcounter{CTAN@unrefs}%
  }{{%
      \def\@CTAN##1##2##3{http://mirror.ctan.org/##2}%
      \href{\csname ctan-#1\endcsname}{#2}%
  }}}
\else % DVI version
  \DeclareRobustCommand{\CTANhref}[2]{\@ifundefined{ctan-#1}{%
      \PackageWarning{CTAN}{Undefined reference: #1}%
      \stepcounter{CTAN@unrefs}%
  }{{%
%     \def\@ctan@path##1{\expandafter\httpify\LocalCTAN!##1}
      \def\@ctan@path##1{\LocalCTAN##1}
      \edef\@tempa{\csname ctan-#1\endcsname}%
      \expandafter\href\expandafter{\@tempa}{#2}%
  }}}
\fi
%
% this is surely temporary
\def\httpify ftp://ftp#1!{http://www#1}
%
% hook for diagnosing undefined references at the end
\AtEndDocument{\ifthenelse{\theCTAN@unrefs > 0}{%
    \PackageWarningNoLine{ctan}{There were \arabic{CTAN@unrefs} undefined
      references to CTAN}%
    }%
    {}%
  \ifthenelse{\theCTAN@replabs > 0}{%
    \PackageWarningNoLine{ctan}{There were \arabic{CTAN@replabs}
      multiply defined references to CTAN}%
    }%
    {}%
}
%
% a slight variation of description for lists of book titles
\newcommand{\booklabel}[1]{\hspace\labelsep\normalfont\itshape #1}
\newenvironment{booklist}{%
  \begin{list}{}%
    {%
      \labelwidth\z@
      \itemindent-\leftmargin
      \let\makelabel\booklabel
      \parskip \z@
      \itemsep \z@
    }%
  }%
  {\end{list}}
%
% proglist is the same as booklist if we're using italics for program
% names, but will need hacking otherwise
\newenvironment{proglist}{\begin{booklist}}{\end{booklist}}
%
% similarly for ctanrefs environment
\newcommand{\ctanreference}[1]{%
  \hspace\labelsep\normalfont\ttfamily\itshape
  \bgroup
    \@makeother\_%
    \scantokens{#1}%
    \unskip
  \egroup
  \/\normalfont:%
}
\newenvironment{ctanrefs}{%
  \begin{list}{}%
    {%
      \labelwidth\z@
      \itemindent-\leftmargin
      \let\makelabel\ctanreference
      \topsep  4\p@
      \parskip \z@
      \itemsep \z@
      \@rightskip=\z@\@plus1in\relax
      \spaceskip=.3333em\relax
      \xspaceskip=.5em\relax
    }%
  }%
  {\end{list}}
%
% compact the itemize, enumerate and description environments
\let\FAQ@@itemize\itemize
\renewcommand\itemize{%
  \topsep  0.25\topsep
  \FAQ@@itemize
  \parskip \z@
  \itemsep \z@
}
\let\FAQ@@enumerate\enumerate
\renewcommand\enumerate{%
  \topsep  0.25\topsep
  \FAQ@@enumerate
  \parskip \z@
  \itemsep \z@
}
\let\FAQ@@description\description
\renewcommand\description{%
  \topsep  0.25\topsep
  \FAQ@@description
  \parskip \z@
  \itemsep \z@
}
%
% and similarly close up verbatim's separation from what surrounds it
\let\FAQ@@verbatim\verbatim
\renewcommand\verbatim{%
  \topsep  0.25\topsep
  \FAQ@@verbatim
}
%
% \raggedwithindent is useful when we've got an URL or something
% overrunning the end of the line (and this line is terminated with
% \\)
%
% Typical usage is within the argument of a \nothtml command
\newcommand\raggedwithindent{%
  \rightskip=\z@\@plus5em\relax
  \spaceskip=.3333em\relax
  \xspaceskip=.5em\relax
  \hangindent=1pc\relax}
%
% things needed for the benefit of texfaq2html's `sanitise_line'
\let\textpercent\%
\let\faq@@textbar\textbar
\chardef\faq@vertbar`\|
\renewcommand\textbar{\def\@tempa{cmtt}%
  \ifx\@tempa\f@family
    \faq@vertbar
  \else
    \faq@@textbar
  \fi
}
%
% redefine \cs{l@section} to  require space for itself at the bottom
% of a column
\renewcommand\l@section[2]{%
  \ifnum \c@tocdepth >\z@
    \addpenalty\@secpenalty
    \addvspace{1.0em \@plus\p@}%
% "needspace" element here (doesn't work)
%   \vskip \z@ \@plus 3\baselineskip
%   \penalty -\@highpenalty
%   \vskip \z@ \@plus -3\baselineskip
    \setlength\@tempdima{1.5em}%
    \begingroup
      \parindent \z@ \rightskip \@pnumwidth
      \parfillskip -\@pnumwidth
      \leavevmode \bfseries
      \advance\leftskip\@tempdima
      \hskip -\leftskip
      #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
    \endgroup
  \fi
}
%
% subsections: these are a curious half-breed between latex sections
% and subsections -- as designed, i'm not intending there ever to be
% more than 9 per section (hahaha)
\renewcommand\subsection{\@startsection{subsection}%
                                       \tw@
                                       \z@
                                       {-1.5ex \@plus-1ex \@minus-.3ex}%
                                       {1ex \@plus.2ex}%
                                       {\normalfont\large\bfseries
                                        \raggedright}%
                        }
\renewcommand*\l@subsection[2]{%
  \ifnum \c@tocdepth >\@ne
    \addpenalty\@secpenalty
    \addvspace{0.5em \@plus\p@}%
% "needspace" element here (doesn't work)
%   \vskip \z@ \@plus 3\baselineskip
%   \penalty -\@highpenalty
%   \vskip \z@ \@plus -3\baselineskip
    \setlength\@tempdima{2.0em}%
    \begingroup
      \parindent \z@ \rightskip \@pnumwidth
      \parfillskip -\@pnumwidth
      \leavevmode \bfseries
      \advance\leftskip\@tempdima
      \hskip -\leftskip
      #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
    \endgroup
  \fi}
%
%
% the question structure
% \Question[label name]{question asked}
% if [label name] present, the named label is assigned with \Qlabel
\newcounter{question}
\newcommand\Question[2][]{%
  \ifpdf
    \def\annot@label{#1}%
    \def\annot@question{#2}%
  \fi
  \edef\l@stl@bel{\@gobbletwo#1}%
  \qu@stion{#2}%
  \def\reserved@a{#1}%
  \ifx\reserved@a\@empty
    \PackageWarning{faq}{Question "#2" has no label}%
  \else
    \Qlabel{#1}%
  \fi
}
\newcommand\qu@stion{\@startsection{question}%
                                   \thr@@
                                   \z@
                                   {-1.25ex \@plus -1ex \@minus -.2ex}%
                                   {0.75ex \@plus .2ex}%
                                   {%
                                     \normalfont
                                     \normalsize
                                     \bfseries
                                     \raggedright
    \protected@edef\@svsec{\protect\annot@set\@svsec}%
                                   }%
}
\newcommand*\questionmark[1]{}
\newcommand*\l@question{\@dottedtocline{2}{2.0em}{2.3em}}

%
% \paragraph: has appeared in a submission, so let's give it a faq
% definition...
\renewcommand\paragraph{\@startsection{paragraph}%
                                       4%
                                       \z@
                                       {1.25ex \@plus 1ex \@minus.2ex}%
                                       {-1em}
                                       {%
                                         \normalfont
                                         \normalsize
                                         \bfseries
                                       }}
%
% alias questions make a little perl script to set up a hash array
% that takes one from old question to current one.
\newcount\aliasfile
\aliasfile=-1
\newcommand\AliasQuestion[1]{%
  \ifnum\aliasfile<0
    \newwrite\aliasfile
    \immediate\openout\aliasfile aliasquestion.list
    \immediate\write\aliasfile {\faq@percent old_label_to_new = (}%)
    \AtEndDocument{%(
      \immediate\write\aliasfile{);}%
      \immediate\write\aliasfile{1;}%
    }%
  \else
    \immediate\write\aliasfile {,}% finish previous line
  \fi
  \immediate\write\aliasfile{"\@gobbletwo#1","\l@stl@bel"}%
}
{%
  \catcode`\!=\the\catcode`\%%
  \catcode`\%=\the\catcode`\+!
  \gdef\faq@percent{%}!
}
%
\long\def\@ReturnAfterFi#1\fi{\fi#1}%
\ifpdf
  \newcommand*\toclevel@question{3}%
  \let\orig@section\section
  \let\orig@subsection\subsection
  \let\orig@subsubsection\subsubsection
  \def\section{%
    \def\toclevel@question{2}%
    \orig@section
  }
  \def\subsection{%
    \def\toclevel@question{3}%
    \orig@subsection
  }
  \def\subsubsection{%
    \def\toclevel@question{4}%
    \orig@subsubsection
  }
  %
  \def\annot@set{%
    \ifx\annot@label\@empty
    \else
      \begingroup
        \def\x##1-##2\@nil{\def\annot@label{##2}}%
        \expandafter\x\annot@label\@nil
        \def\x##1_##2\@nil{%
          ##1%
          \ifx\\##2\\%
          \else
            \noexpand\textunderscore
            \@ReturnAfterFi{\x##2\@nil}%
          \fi
        }%
        \edef\annot@label{\expandafter\x\annot@label_\@nil}%
        \edef\NL{\string\n}%
        \pdfstringdef\annot@text{%
          http://www.tex.ac.uk/cgi-bin/texfaq2html?label=\annot@label\NL
          \annot@question
        }%
        \rlap{%
          \kern-10mm\relax
          \settoheight{\dimen@}{X}%
          \pdfannotlink
            width 200mm
            height \dimen@
            depth 25mm
            user {%
              /Subtype/Text%
              /T(Question \thequestion: \annot@label)%
              /Contents(\annot@text)%
            }%
          \pdfendlink
        }%
      \endgroup
    \fi
  }%
  \@ifundefined{pdfannotlink}{%
    \let\pdfannotlink\pdfstartlink
  }{}
\else
  \let\annot@set\relax
\fi
%
% \QuestionLabel starts out as a null command (so that inputting a
% .lab file at s.o.d has no effect), but it's then reset to
% \@questionLabel in case the file is going to be read again later
% (e.g., as an appendix), but we don't have a sensible definition of
% _that_ yet, either...
\newcommand{\labellist}{%
  \newcommand{\QuestionLabel}[3]{}%
%  \@starttoc{lab}%
  \let\QuestionLabel\@questionLabel
}
\newcommand{\@questionLabel}[3]{}
%
% \afterquestion is used when the \Question command itself has to be
% inside a group for some reason (e.g., to have it in \boldmath)
\newcommand\afterquestion{%
  \global\toks@\expandafter{\the\everypar}%
  \edef\@tempa{%
    \noexpand\@afterindentfalse
    \noexpand\everypar{\the\toks@}%
  }%
  \expandafter\endgroup\@tempa
}
%
% \cs{Destination} is used immediately after a \cs{Question} command
% in the various add-* files to signify where the question is supposed
% to go
\newcommand\Destination[1]{\begin{center}
    \itshape#1
  \end{center}
}
%
% we `number' our sections alphabetically
\renewcommand{\thesection}{\Alph{section}}
%
% keywords for questions.  these get translated into comments in web
% versions
\newcommand\keywords{\begingroup
  \@makeother\\%
  \@makeother\^%
  \@makeother\_%
  \@makeother\%%
  \expandafter\endgroup
  \@gobble
}
%
% date question last edited
\def\LastEdit{\@ifstar\@gobble\@gobble}
%
% where the info came from
\newcommand\LeadFrom[3]{}
%
% \Qlabel and \Qref: define and refer to labels
\ifpdf
% hyperref version of \label doesn't get set until begin document
  \AtBeginDocument{\let\Qlabel\label}
\else
  \let\Qlabel\label
\fi
% \Qref[<text before q no>]{<hyper anchor text>}{<question label>}
% (default for arg 1 is "see question"; a conventional null argument
%  here is \htmlonly, which gobbles a space)
% produces:
%       <text before q no> <question number>
%
% \Qref*... produces
%       <hyper anchor text> (<text before q no> <question number>)
%
% the code is supposed to deal correctly with things surrounded by
% double quotes (i.e., ``\Qref*....'' closes the quotes before putting
% the question number in parentheses.
%
% this stuff should be reconsidered to produce more sensible behaviour
% when running pdftex
%
\ifpdf
%
% if we're using pdflatex, we let hyperref take the strain, and make
% \Qrefs look like the html versions
\DeclareRobustCommand\Qref{\@ifstar\@QrefH\@QrefH}
\newcommand\@QrefH[3][\relax]{%
  \expandafter\let\expandafter\reserved@a\csname r@#3\endcsname
  \ifx\reserved@a\relax
    \protect\G@refundefinedtrue
    \nfss@text{\reset@font\bfseries ??}%
    \@latex@warning{%
      Reference `#3' on page \thepage \space undefined%
    }%
  \else
%   \protected@edef\reserved@b{\reserved@a}%
    \def\reserved@c##1##2##3##4##5{%
      \def\reserved@d{{##1}{##2}{#2}{##4}{##5}}%
    }%
    \expandafter\reserved@c\reserved@a
    \expandafter\Hy@setref@link\reserved@d\@empty\@empty\@nil\@thirdoffive
  \fi
}
\else
%
% not using pdflatex: we've a ghastly job on our hands...
\newcommand\Qref{\@ifstar\@QrefA\@QrefB}
\newcommand\@QrefA[3][see question]{#2%
  \def\@QrefAai{#1}%
  \def\@QrefAaiii{#3}%
  \afterassignment\@QrefAl\let\@tempa= }
\newcommand\@QrefAl{% \@tempa is char after original \Qref's args
  % \@QrefAai/\@QrefAaiii are arguments of \Qref
  \ifx\@tempa'%
    \def\@next{%
      \afterassignment\@QrefAQ
      \let\@tempa= %
    }%
    \expandafter\@next
  \else
    { (\@QrefAai~\ref{\@QrefAaiii})\@tempa}%
  \fi
}
\newcommand\@QrefAQ{% \@tempa is second char after original \Qref's
   % arguments (first was a quote character)
  \ifx\@tempa'%
    '' (\@QrefAai~\ref{\@QrefAaiii})%
  \else
    { (\@QrefAai~\ref{\@QrefAaiii})'\@tempa}%
  \fi
}
%%   \@ifnextchar'{\@QrefAQb{#1}{#2}}{ (#1~\ref{#2})'}}
%% \newcommand\@QrefAQb[3]{% param 3 quote again
%%   '' (#1~\ref{#2})}
\newcommand\@QrefB[3][see question]{#1~\ref{#3}}
%
\fi
%
% from doc package, then hacked about by yours truly
\DeclareRobustCommand\csx[1]{{\FAQverbFamily\char`\\#1}}
%\def\cs|#1|{\csx{#1}}
%
% fancier versions of the above
%
% \cmdinvoke\cs<argument sequence>
% \cs typeset as above
% <argument sequence> may consist of optional or mandatory arguments;
%
% the `arguments' are simply typesett \texttt, as yet -- if something
% fancier is needed, there's a bunch of code needs rewriting here...
\DeclareRobustCommand\cmdinvoke{\@ifstar
  {\let\@tempa\emph\@scmdinvoke}%
  {\let\@tempa\relax\@scmdinvoke}%
}
\def\@scmdinvoke#1{\texttt{\symbol{92}#1}%
  \futurelet\@let@token\@cmdinvoke
}
\def\@cmdinvoke{\ifx\@let@token\bgroup
    \let\@tempb\@cmdinvoke@lbrace
  \else
    \ifx\@let@token[% ]
      \let\@tempb\@cmdinvoke@lbrack
    \else
      \ifx\@let@token(% )
        \let\@tempb\@cmdinvoke@lparen
      \else
        \let\@tempb\@empty
      \fi
    \fi
  \fi
  \@tempb
}
\def\@cmdinvoke@lbrace#1{\penalty0\hskip0pt\relax
  \texttt{\symbol{123}\@tempa{#1}\symbol{125}}%
  \futurelet\@let@token\@cmdinvoke
}
\def\@cmdinvoke@lbrack[#1]{\penalty-150\hskip0pt\relax
  \texttt{[\@tempa{#1}]}%
  \futurelet\@let@token\@cmdinvoke
}
\def\@cmdinvoke@lparen(#1){\penalty-150\hskip0pt\relax
  \texttt{(\@tempa{#1})}%
  \futurelet\@let@token\@cmdinvoke
}
%
% for writing \cmdinvoke out by hand (in titles)
\def\marg#1{\texttt{\symbol{123}{#1}\symbol{125}}}

% that stuff doesn't work in pdf thumbnails.  herewith an alternative
% for label ps@empty:
\DeclareRobustCommand\psatempty{%
  \texttt{\string\pagestyle\string{empty\string}}%
}

% minuscule bit more structured markup...
\newcommand\environment[1]{\texttt{#1}}
\newcommand\pkgoption[1]{\texttt{#1}}
\newcommand\extension[1]{\texttt{.#1}}
\newcommand\ltxcounter[1]{\texttt{#1}}
\newcommand\FontFormat[1]{\texttt{#1}}

% deal with tabular: special defs to make texfaq2html doable
\let\tbamp&
\def\tbeol{\\}
\def\tbhline{\midrule}

%
% symbols for the braces (which can confuse perl sumfink rotten
\def\obracesymbol{\symbol{123}}
\def\cbracesymbol{\symbol{125}}

%
% for quoting verbatim environments in examples:
\begingroup \catcode `|=0 \catcode `[= 1
\catcode`]=2 \catcode `\{=12 \catcode `\}=12
\catcode`\\=12
|gdef|@quotexverbatim#1\end{quoteverbatim}[#1|end[quoteverbatim]]
|endgroup
\def\quoteverbatim{\@verbatim \frenchspacing\@vobeyspaces \@quotexverbatim}
\let\endquoteverbatim\endverbatim

%
% for comments during maintenance
%\def\Q#1{\footnote{{\ttfamily QUERY: #1}}}
%\def\Q#1{\marginpar{{\ttfamily QUERY: #1}}}
%
% Checking structure (null for now)
\newcommand\checked[2]{}
%
% for Alan's benefit
\newbox\@footnoteenvbox
\newenvironment{footnoteenv}
  {\begin{lrbox}\@footnoteenvbox\reset@font\footnotesize\ignorespaces}
  {\end{lrbox}%
   \footnote{\unhbox\@footnoteenvbox}}
%
% end of package
\endinput