path: root/Master/texmf-dist/source/latex/gcite/gcite.dtx

%\iffalse
% gcite.dtx generated using makedtx version 0.94b (c) Nicola Talbot
% Command line args:
%   -setambles "gcite\.bib=>\nopreamble\nopostamble"
%   -src "gcite\.sty=>gcite.sty"
%   -src "gcite\.bib=>gcite.bib"
%   -doc "gcite.tex"
%   -author "Matthew Tylee Atkinson and Iain Phillips"
%   -license "lppl"
%   gcite
% Created on 2007/9/5 15:19
%\fi
%\iffalse
%<*package>
%% \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         \~}
%</package>
%\fi
% \iffalse
% Doc-Source file to use with LaTeX2e
% Copyright (C) 2007 Matthew Tylee Atkinson and Iain Phillips, all rights reserved.
% \fi
% \iffalse
%<*driver>
%%%
%%% gcite manual
%%% Matthew Tylee Atkinson
%%% Package code written with Iain Phillips
%%%
\documentclass[british,a4paper]{ltxdoc}
\usepackage{babel}
\usepackage[hyperref=true]{biblatex}
\usepackage[colorlinks,breaklinks,linktocpage,pdftitle={The gcite Package},pdfauthor={Matthew Tylee Atkinson and Iain Phillips},pdfsubject={}]{hyperref}
\usepackage{gcite}
%%%
%%% Header information
%%%
\title{The \pkg{gcite} Package\\\large Citations in the German\thanks{footnotes containing brief information and standard numeric links to bibliography entries with full information}~ Style \\ Version 1.0.0}
\author{Matthew Tylee Atkinson\\\email{M.T.Atkinson@lboro.ac.uk} \and Iain Phillips\\\email{I.W.Phillips@lboro.ac.uk}}
\date{2nd September 2007}

%%%
%%% Macros
%%%
\newcommand{\pkg}[1]{%
    \textsf{#1}}
\newcommand{\opt}[1]{%
    \textsf{#1}}
\newcommand{\email}[1]{%
    \texttt{#1}}
\newcommand{\biblatexSecPage}[2]{%
    (section #1; page #2)}
%%%
%%% ``Teh'' Document
%%%
\bibliography{gcite}
\begin{document}
\DocInput{gcite.dtx}
\end{document}
%</driver>
%\fi
%\maketitle
%\begin{abstract}
%This package allows you to make citations in the German style, which is considered by many to be particularly reader-friendly. The citation provides a small amount of bibliographic information in a footnote on the page where each citation is made.  It combines a desire to eliminate unnecessary page-turning with the look-up efficiency afforded by numeric citations.
%\end{abstract}
%\tableofcontents\clearpage
%
%\section{Introduction}
%
%When writing a document, the aim should be to make the reading process as smooth as possible.  You may well enjoy using the numeric style of citations, but this means that no information on the cited works is made available at the point of citation in the text.
%
%One answer to this the German citation style, which is implemented by the \pkg{gcite} package.  It will print some limited information about cited works\cite{Dhiensa2005} in a footnote and still provide a traditional numeric link to the bibliography.  Using \pkg{gcite} offers more information than the author-year citation format and keeps the fast indexing ability of using numeric citations.
%
%The package can also deal with multi-key citations, as with the traditional \LaTeX\ |\cite{}| command\cite{opcit,AGRIP}.
%
%\section{Prerequisites}
%
%The \pkg{gcite} package requires that you use \pkg{biblatex}.  This package implements most of the functionality of \BibTeX\ in \LaTeX\ and provides commands that allow lower-level access to bibliographic data than the standard |\cite{}| command.
%
%It is recommended that you read the documentation for the \pkg{biblatex} package\cite{biblatex}.  However, what follows is a short overview of the few steps needed to turn a standard \LaTeX\ document into one that will work with \pkg{biblatex}.
%
%\begin{enumerate}
%\item |\usepackage[hyperref=true]{biblatex}| \emph{before} \pkg{hyperref} is loaded, if you're using it (if not you can ignore the \opt{hyperref} option completely).
%
%\item Move your |\bibliography{}| command to the document's preamble (e.g. directly before |\begin{document}|).
%
%\item Remove the |\bibliographystyle{}| command.
%
%\item Add |\printbibliography| where you want the bibliography to be generated.  Use |\printbibliography[heading=bibintoc]| if you want the bibliography section to show up in the table of contents of your document.
%\end{enumerate}
%
%\section{Usage}
%
%\DescribeMacro{\usepackage\{gcite\}} To use the \pkg{gcite} package, simply load it.
%
%All of your citation commands will then be overridden with the new behaviour.  However, as you will most likely have ensured that a space---or non-breaking space---character precedes every |\cite{}| command, you will need to remove that space or there will be a noticeable gap before each footnote mark generated by your |\cite{}| commands.
%
%\subsection{Removing Now-Unnecessary Spacing}
%
%You'll need to do a search and replace to remove these undesired spaces.  Depending on your editor and \LaTeX-writing style, the method for doing this will differ.  The most likely search pattern will be |~| (non-breaking space) and this should be replaced with literally nothing, turning \LaTeX\ code such as
%
%\begin{verbatim}
%...in the previous work~\cite{paper}...
%\end{verbatim}
%
%into
%
%\begin{verbatim}
%...in the previous work\cite{paper}...
%\end{verbatim}
%
%In the text editors that support regexps, this can be achieved by executing the command to convert from |/~\\cite/| to |/\\cite/|.  You should specify the ``g'' (``global'') modifier to ensure all matches on each line are substituted.  In Vim, this command is |%s/\~\\cite/\\cite/g|.
%
%\subsection{Recommended Citation Style}
%
%All of the examples in this manual were created using \pkg{biblatex}'s default style of citation markers.  This is the same as the ``plain'' bibliography style in normal \LaTeX/\BibTeX\ and is the recommended style for use with \pkg{gcite}, because it allows for fast indexing into the bibliography section.
%
%You are, however, free to choose whichever style of citation you like---\pkg{gcite} will still encapsulate it into a footnote as in the examples presented here.
%
%\subsection{Multi-Key Citations}
%
%Sometimes you will wish to cite only one piece of work to prove a point and, at other times, multiple works ought to be cited.  The traditional |\cite{}| command groups multi-key citations together (i.e. multiple numbers, separated by commas, can be found inside the square brackets).
%
%\pkg{gcite} groups multi-key citations similarly, outputting the minimal bibliographic details for each work in turn, then the grouped numeric citation at the end.  Section~\ref{sec:customisation:multi} contains information on how the separator used may be customised.
%
%\subsection{Citations Within Footnotes}
%
%There may be occasions when you may wish to make a citation from within a |\footnote{}|.  In this case, \pkg{gcite} will not create a new footnote, but continue using the existing one\footnote{as shown in this example\cite{AGRIP}}.  Section~\ref{sec:customisation:foot} contains some information on how this behaviour may be customised.
%
%\subsection{Reverting to the Standard Behaviour}
%
%It is possible to revert to the standard \LaTeX/\BibTeX\ citation behaviour.  Two methods are provided (to cater for global and local reversion).
%
%\subsubsection{The \opt{normalcite} Option}
%
%\DescribeMacro{\usepackage[normalcite]\\\{gcite\}}  Simply specify the \opt{normalcite} option when loading \pkg{gcite} and the standard behaviour will be restored for all citations in your document.
%
%Please note that if you use this method, you'll not be required to re-insert spaces before each |\cite{}| command---\pkg{gcite} will insert them for you.
%
%\subsubsection{One-Off Citations in the Standard Style}
%
%\DescribeMacro{\origcite\{\}} If you wish to make relatively few citations in the standard \LaTeX/\BibTeX\ style, you can use this command.  It will affect only the current citation being made and \emph{does} require that a space (non-breaking or otherwise) be inserted before it.
%
%This command is provided for special cases (such as an appendix to a thesis that lists prior publications) where adding the footnotes would be repeating information.  It is not intended to be used often, or even at all, by most users.
%
%\section{Customisation}
%
%There are a few customisation options provided by the \pkg{gcite} package.  They allow some control over the way that citations are presented.
%
%\subsection{Multi-Key Item Separator}
%\label{sec:customisation:multi}
%
%\DescribeMacro{\gciteitemsep\{\}} The default separator between items (cited works) in a multi-key citation is the semicolon, followed by a space.  This can be easily changed by using the |\gciteitemsep| command.  The example below shows the separator being set to the bullet point symbol, with a space on either side.
%
%\gciteitemsep{ \textbullet\ }
%\begin{verbatim}
%\gciteitemsep{ \textbullet\ }
%\end{verbatim}
%
%It is possible to use this command anywhere in your document.  After doing so, the effects of having adjusted the citation separator can be seen\cite{biblatex,Dhiensa2005,Stone2004}.
%
%\subsection{Footnote Citation Separators}
%\label{sec:customisation:foot}
%
%\DescribeMacro{\gcitefoot*sep\{\}} As discussed above, citations may be made inside footnotes.  In this case, a separator is placed between the footnote text and citation text \emph{and} at the end of the citation text.  The default pre-citation text separator is the em-dash (``---'') and the default post-citation text separator is literally nothing.  As with the multi-key separator above, both of these may be customised.  Some examples follow.
%
%In this example, we redefine only the pre-citation text separator.
%
%\gcitefootpresep{: }
%\begin{verbatim}
%\gcitefootpresep{: }
%\end{verbatim}
%
%These commands may also be used anywhere in your document\footnote{and here is an example\cite{makedtx}}.  Below is an example where both the pre- and post- separators are set.
%
%\gcitefootpresep{ (}
%\gcitefootpostsep{)}
%\begin{verbatim}
%\gcitefootpresep{ (}
%\gcitefootpostsep{)}
%\end{verbatim}
%
%Once again, the effect of executing these commands can be seen below\footnote{Setting both a pre- and post-citation separator has an effect like this\cite{AGRIP}.}.
%
%\printbibliography[heading=bibnumbered]
%\appendix
%\section{Help for Newcomers to \pkg{biblatex}}
%
%\begin{quote}
%``Don't Panic!''\\
%---Douglas Adams, ``The Hitchhiker's Guide to the Galaxy''
%\end{quote}
%
%\gcitefootpresep{}
%\gcitefootpostsep{; }
%
%Below is a list of things that people new to the \pkg{biblatex} package need to be aware of.  Information on how to solve some potential problems is given, along with section and page number links to the \pkg{biblatex} documentation\footnote{\cite{biblatex}referenced manual section and page numbers are correct for version 0.6 beta (6th January 2007)} that you can use to find out more.
%
%\gcitefootpresep{---}
%\gcitefootpostsep{}
%
%\begin{description}
%\item[No \BibTeX\ custom styles]--- Only styles made for \pkg{biblatex} may be used.  This is not foreseen to be a problem in reality, as using \pkg{gcite} implies that the user has a particular (implemented) style in mind, but it is worth mentioning \biblatexSecPage{2}{2}.
%
%\item[More fields used]--- \pkg{biblatex} by default prints out more information from your |.bib| file(s).  Fields such as ``howpublished'', ``doi'' and ``url'' are typeset by default \biblatexSecPage{2.1.1}{3--5}.
%
%It is possible to create your own bibliography style that suppress this extra information.  The manual provides details \biblatexSecPage{4.2 [specifically 4.2.1 and 4.2.3]}{67--73} and the file |biblatex/bbx/standard.bbx| provides a useful template.
%
%\item[|Missing \$ inserted| compilation error]--- This can be caused by invalid (special) characters appearing in certain fields in the |.bib| file(s).  It may have gone un-noticed until now due to \pkg{biblatex}'s default inclusion of more field types than \BibTeX\ in the typeset document.  One example cause is the special characters (such as: `\_'; `\&' and `\%') in a URL, if one is present in a field other than ``url'' (those \emph{inside} a ``url'' field will be automatically escaped).
%
%Make sure URLs are specified only in the ``url'' field and that special characters\footnote{see \url{http://theoval.cmp.uea.ac.uk/~nlct/latex/novices/node30.html}; last accessed 1st September 2007} in any other fields are escaped.  The error message may tell you the line in any external file to the document (such as the intermediate |.bbl| file) where the error occurred.
%
%\item[Non-American localisation]--- As \pkg{biblatex} prints out more fields than \BibTeX\ by default, including URL access dates, you may need to carry out some localisation to ensure these fields are typeset in an appropriate way for your country.
%
%A simple way to do this is to use the \pkg{babel} package\footnote{\url{http://www.ctan.org/tex-archive/macros/latex/required/babel/}; last accessed 1st September 2007}.  Specify your language string (as listed in the \pkg{babel} documentation) as one of the options to |\documentclass[]{}|, then ensure you |\usepackage{babel}|.  This way, all packages that support automatic localisation will pick up your language option.  \pkg{biblatex} will reflect this too (and will do things such as use your local date format and provide some string translations as a result).
%\end{description}
%
%
%\StopEventually{}
%\section{The Code}
%\iffalse
%    \begin{macrocode}
%<*gcite.sty>
%    \end{macrocode}
%\fi
% Package definition.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{gcite}
\RequirePackage{biblatex}
%    \end{macrocode}
% Define our \opt{normalcite} option and set it to false by default.
%    \begin{macrocode}
\newif\ifgcite@normalcite
\gcite@normalcitefalse
\DeclareOption{normalcite}{\gcite@normalcitetrue}
\ProcessOptions\relax
%    \end{macrocode}
% \subsection{Minor Bits}
% Move the traditional |\cite{}| command out of the way.
%    \begin{macrocode}
\let\origcite\cite
%    \end{macrocode}
% Provide a way to customise the separator used between individual cited works.
%    \begin{macrocode}
\providecommand{\gciteitemsep}[1]{\def\gcite@itemsep{#1}}
%    \end{macrocode}
% Default multi-item separator is semicolon with a space following.
%    \begin{macrocode}
\def\gcite@itemsep{; }
%    \end{macrocode}
% Provide a way to customise the separator used between the footnote text and the citation text when a citation is made from inside a footnote.
%    \begin{macrocode}
\providecommand{\gcitefootpresep}[1]{\def\gcite@foot@presep{#1}}
\providecommand{\gcitefootpostsep}[1]{\def\gcite@foot@postsep{#1}}
%    \end{macrocode}
% Default footnote citation text pre-separator is an em-dash; default post-seperator is literally nothing.
%    \begin{macrocode}
\def\gcite@foot@presep{---}
\def\gcite@foot@postsep{}
%    \end{macrocode}
% \subsection{Core Commands}
% The core commands of the German citation style produce the short version(s) of the bibliographical information, followed by a pointer to the full citation in the bibliography.  They are called internally.
%
% Each individual cited work's details must be treated atomically.
%    \begin{macrocode}
\def\gcite@one#1{\citeauthor{#1}, \citetitle{#1}, \citeyear{#1}}
%    \end{macrocode}
% We need a loop to output the details of each cited work in turn, then display the numerical link(s) at the end.
%    \begin{macrocode}
\def\gcite@core#1{%
    \newif\ifgcite@nfirst
    \gcite@nfirstfalse%
    \@for\@c:=#1\do{%
        \ifgcite@nfirst{\gcite@itemsep}\else\gcite@nfirsttrue\fi%
        \gcite@one\@c} \origcite{#1}}
%    \end{macrocode}
% \subsection{Citation Command Replacement}
% If the \opt{normalcite} option was specified, simply emulate the standard \LaTeX\ behaviour (including the non-breaking space).
%    \begin{macrocode}
\ifgcite@normalcite%
    \renewcommand{\cite}[1]{%
        ~\origcite{#1}%
    }
\else%
%    \end{macrocode}
% Otherwise, we use the \pkg{gcite} behaviour.
%    \begin{macrocode}
    \renewcommand{\cite}[1]{%
%    \end{macrocode}
% Here is a wrapper to decide if we're in a footnote or not.  The idea was gained from the \pkg{opcit} package\cite{opcit}.
%    \begin{macrocode}
        \ifnum\interlinepenalty=\interfootnotelinepenalty%
%    \end{macrocode}
% We are in a footnote---just add the text of the footnote citation to the end of the current footnote, separating it from the rest of the footnote text, if the user wishes.
%    \begin{macrocode}
            \gcite@foot@presep\gcite@core{#1}\gcite@foot@postsep%
        \else%
%    \end{macrocode}
% Otherwise, we're not in a footnote, so create a new one.
%    \begin{macrocode}
            \footnote{\gcite@core{#1}}%
        \fi%
    }
\fi
%    \end{macrocode}
% That's all, folks!
%\iffalse
%    \begin{macrocode}
%</gcite.sty>
%    \end{macrocode}
%\fi
%\iffalse
%    \begin{macrocode}
%<*gcite.bib>
%    \end{macrocode}
%\fi
% \iffalse
%    \begin{macrocode}
@Misc{		  makedtx,
  author	= "Nicola Talbot",
  title		= "{makedtx : a Perl script to help create a DTX file from
		  source code}",
  url		= "http://www.ctan.org/tex-archive/support/makedtx/",
  urldate	= {2007-09-02},
  year		= "2005"
}

@Misc{		  opcit,
  author	= "Federico Garcia",
  title		= "{opcit (version 2.0) a package for footnote-style
		  bibliographical references}",
  url		= "http://www.ctan.org/tex-archive/macros/latex/contrib/opcit/"
		  ,
  urldate	= {2007-09-02},
  year		= "2006"
}

@Misc{		  biblatex,
  author	= "Philipp Lehman",
  title		= "{The biblatex package}",
  url		= "http://www.ctan.org/tex-archive/macros/latex/exptl/biblatex/"
		  ,
  urldate	= {2007-09-02},
  year		= "2006"
}

@Misc{		  agrip,
  author	= "Matthew Tylee Atkinson and Sabahattin Gucukoglu",
  title		= "{Accessible Gaming Rendering Independence Possible}",
  url		= "http://www.agrip.org.uk/",
  month		= "05",
  year		= "2003"
}

@InProceedings{	  dhiensa2005,
  author	= "Jatinder Dhiensa and Colin Machin and Francesca Smith and
		  Roger Stone",
  title		= "Optimizing the User Environment: Leading Towards an
		  Accessible and Usable Experience",
  booktitle	= "Accessible Design in the Digital World Conference 2005",
  year		= "2005",
  issn		= "1477-9358",
  location	= "Dundee, Scotland",
  pdf		= "paper3.pdf"
}

@InProceedings{	  stone2004,
  author	= "R. G. Stone and J. Dhiensa",
  title		= "Proving the validity and accessibility of dynamic
		  web-pages",
  booktitle	= "W4A '04: Proceedings of the 2004 international
		  cross-disciplinary workshop on Web accessibility (W4A)",
  year		= "2004",
  pages		= "45--49",
  address	= "New York, NY, USA",
  publisher	= "ACM Press",
  doi		= "http://doi.acm.org/10.1145/990657.990665",
  isbn		= "1-58113-903-9",
  pdf		= "p45-stone.pdf"
}
%    \end{macrocode}
% \fi
%\iffalse
%    \begin{macrocode}
%</gcite.bib>
%    \end{macrocode}
%\fi
%\Finale
\endinput