% $Id: //depot/Master/texmf-dist/doc/pdftex/base/pdftex-pdfkeys/pdftex-pdfkeys.tex#1 $
%      Copyright (c)  2001 Martin Schröder
%      Permission is granted to copy, distribute and/or modify this document
%      under the terms of the GNU Free Documentation License, Version 1.1 or
%      any later version published by the Free Software Foundation; with
%      no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
%      Texts.
%      A copy of the license is included in the appendix entitled "GNU Free
%      Documentation License".
%
% The layout of this document tries to mimic that of the PDF reference.
\pdfoutput=1
\pdfcompresslevel=9
\pdfdecimaldigits=5
\documentclass[a4paper,oneside,bibtotoc,openany,pdftex]{scrbook}
\usepackage[latin1]{inputenc}
\usepackage[pdfpagelabels]{hyperref}
\usepackage{thumbpdf}
\usepackage{filecontents}
\usepackage{ltxtable,booktabs}
\usepackage{xspace}
\usepackage{relsize}
\usepackage{prelim2e}
\newcommand{\documentversion}{0.12}
\renewcommand{\PrelimText}{%
   \textnormal{%
      \footnotesize%
      \PrelimTextStyle%
      Version \documentversion{} -- 2002-05-10
      }%
   }

%--------------

\hypersetup{colorlinks,
    bookmarksnumbered,
    pdftitle={Additional PDF keys inserted by pdfTeX},
    pdfauthor={Martin Schröder}}

\newenvironment{keytable}[1]
% Usage:
% \begin{filecontents}{foo}
% \begin{keytable}{caption}
% \pdfkey...
% \end{keytable}
% \end{filecontents}
% \LTXtable{\textwidth}{foo}
    {%
    \begin{longtable}{ll>{\raggedright}X}
    \caption{#1}\belowpdfbookmark{Table \thetable{} #1}{table:\thetable}\\
    \toprule
    \sffamily\slshape Key & \sffamily\slshape Type & \sffamily\slshape Semantics \tabularnewline
    \midrule\addlinespace[1ex]
    \endfirsthead
    \caption[]{(continued)}\\
    \toprule
    \sffamily\slshape Key & \sffamily\slshape Type & \sffamily\slshape Semantics \tabularnewline
    \midrule\addlinespace[1ex]
    \endhead
    \bottomrule
    \endfoot
    }{\end{longtable}%
    }
\newcommand*{\pdfkey}[3]{\bfseries #1 & #2 & #3\tabularnewline}

\newenvironment{history}
    {%
    \begin{longtable}{lll>{\raggedright}X}
    \caption{History}\belowpdfbookmark{Table \thetable{} History}{table:\thetable}\\
    \toprule
    Version & When & Who & What \tabularnewline
    \midrule\addlinespace[1ex]
    \endfirsthead
    \caption[]{(continued)}\\
    \toprule
    Version & When & Who & What \tabularnewline
    \midrule\addlinespace[1ex]
    \endhead
    \bottomrule
    \endfoot
    }{\end{longtable}%
    }
\newcommand*{\historyentry}[4]{#1 & #2 & #3 & #4\tabularnewline}

%--------------

\deffootnote{1em}{1em}{\textsuperscript{\normalfont{\thefootnotemark}}}

%--------------

\newcommand{\pt}{pdf\TeX\xspace}
\newcommand{\eg}{e.\,g.\xspace}
\newcommand*{\key}[1]{\textsf{\textbf{#1}}\xspace}

%--------------
\begin{document}
\frontmatter
\title{Additional PDF keys inserted by \pt\\[1ex]
       \relsize{-2} Version \documentversion}
\author{Martin Schröder%
     \thanks{ArtCom GmbH\newline
             Grazer Straße 8\newline
             28359 Bremen\newline
             Germany\newline
             \texttt{ms@artcom-gmbh.de}}
     }
\maketitle

\tableofcontents
\listoftables

%--------------

\chapter*{Copyright}

Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU Free Documentation License, Version 1.1 or any later version
published by the Free Software Foundation; with no Invariant Sections, with no
Front-Cover Texts, and with no Back-Cover Texts.
A copy of the license is included in appendix \ref{chap:fdl}.

%--------------
\mainmatter
\chapter{Introduction}

A PDF document should contain only the structures and attributes defined in
the PDF specification \cite{Adobe:2001:PRA}. 
But the specification allows applications to insert additional keys,
provided they follow certain rules \cite[Appendix F]{Adobe:2001:PRA}.

The most important rule is that developers have to register with Adobe prefixes
for the keys they want to insert. 
This has been done for \pt: Hans Hagen has registered the prefix ``PTEX''.

As this prefix is all caps keys should start with an additional ``.''. 

\section{History}
\begin{filecontents}{ltxtable.inc}
\begin{history}
\historyentry{0.12}
             {2002-05-10}
             {Martin Schr\"oder}
             {Fixed typo in Copyright; refer to \cite{Adobe:2001:PRA}
             instead of \cite{Adobe:2000:PRA} and updated the terminology.}
\historyentry{0.11}
             {2001-11-05}
             {Martin Schr\"oder}
             {Added \key{PTEX.InfoDict}}
\historyentry{0.1}
             {2001-10-10}
             {Martin Schr\"oder}
             {Initial version}
\end{history}
\end{filecontents}
\LTXtable{\textwidth}{ltxtable.inc}

%--------------
\chapter{XObjects (included PDF)}

\pt generates an XObject for every included PDF.
The dictionary of this object contains these additional keys:

\begin{filecontents}{ltxtable.inc}
\begin{keytable}{Attributes in XObjects of included PDF}
\pdfkey{PTEX.FileName}{string}{The name of the included file as seen by \pt.}
\pdfkey{PTEX.InfoDict}{dictionary}{\emph{(Indirect)} The document
                                  information dictionary of the included
                                  PDF.}
\pdfkey{PTEX.PageNumber}{integer}{The page number of the included file.}
\end{keytable}
\end{filecontents}
\LTXtable{\textwidth}{ltxtable.inc}

%--------------
\chapter{Document Catalog}

Although it would seem more natural to put this infomation in the document
information dictionary, the PDF reference says
\cite[p.\,575]{Adobe:2001:PRA}: 
\begin{quote}
Although viewer applications can store custom metadata in the document
information dictionary, it is inappropriate to store private content or
structural information there; such information should be stored in the
document catalog instead (see Section 3.6.1, Document Catalog).
\end{quote}

\begin{filecontents}{ltxtable.inc}
\begin{keytable}{Catalog attributes}
\pdfkey{PTEX.Fullbanner}{string}{The full version of the \pt binary that
                                 produced the file as displayed by
                                 \texttt{pdftex -\/-version}, \eg\ ``This is
                                 pdfTeX, Version
                                 3.14159-1.00a-pretest-ArtCom-20011008''.\newline
                                 This is necessary because the string in the
                                 \key{Producer} key in the Info dictionary
                                 is rather short, \eg\ ``pdfTeX-1.0a-pdfcrypt''.} 
\end{keytable}
\end{filecontents}
\LTXtable{\textwidth}{ltxtable.inc}

%--------------
\appendix
\include{fdl}

%--------------
\backmatter
\bibliographystyle{plain}
\bibliography{postscri}

\end{document}