Debian Codegraph @

texmf-dist/source/latex/gcite/gcite.dtx

raw
1 %\iffalse
2 % gcite.dtx generated using makedtx version 0.94b (c) Nicola Talbot
3 % Command line args:
4 % -setambles "gcite\.bib=>\nopreamble\nopostamble"
5 % -src "gcite\.sty=>gcite.sty"
6 % -src "gcite\.bib=>gcite.bib"
7 % -doc "gcite.tex"
8 % -author "Matthew Tylee Atkinson and Iain Phillips"
9 % -license "lppl"
10 % gcite
11 % Created on 2009/7/4 13:22
12 %\fi
13 %\iffalse
14 %<*package>
15 %% \CharacterTable
16 %% {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
17 %% 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
18 %% Digits \0\1\2\3\4\5\6\7\8\9
19 %% Exclamation \! Double quote \" Hash (number) \#
20 %% Dollar \$ Percent \% Ampersand \&
21 %% Acute accent \' Left paren \( Right paren \)
22 %% Asterisk \* Plus \+ Comma \,
23 %% Minus \- Point \. Solidus \/
24 %% Colon \: Semicolon \; Less than \<
25 %% Equals \= Greater than \> Question mark \?
26 %% Commercial at \@ Left bracket \[ Backslash \\
27 %% Right bracket \] Circumflex \^ Underscore \_
28 %% Grave accent \` Left brace \{ Vertical bar \|
29 %% Right brace \} Tilde \~}
30 %</package>
31 %\fi
32 % \iffalse
33 % Doc-Source file to use with LaTeX2e
34 % Copyright (C) 2009 Matthew Tylee Atkinson and Iain Phillips, all rights reserved.
35 % \fi
36 % \iffalse
37 %<*driver>
38 %%%
39 %%% gcite manual
40 %%% Matthew Tylee Atkinson
41 %%% Package code written with Iain Phillips
42 %%%
43 \documentclass[british,a4paper]{ltxdoc}
44 \usepackage{babel,color}
45 \usepackage[hyperref=true]{biblatex}
46 \definecolor{darkblue}{rgb}{0, 0, 0.5}
47 \definecolor{darkgreen}{rgb}{0, 0.5, 0}
48 \usepackage[colorlinks,linkcolor=darkblue,citecolor=darkgreen,breaklinks,linktocpage,pdftitle={The gcite Package},pdfauthor={Matthew Tylee Atkinson and Iain Phillips},pdfsubject={}]{hyperref}
49 \usepackage{gcite}
50
51 \title{The \pkg{gcite} Package\\\large Citations in the German\footnote{footnotes containing brief information and standard numeric links to bibliography entries with full information}~~Style \\ Version 1.0.1}
52 \author{Matthew Tylee Atkinson\\\email{[email protected]} \and Iain Phillips\\\email{[email protected]}}
53 \date{3rd July 2009}
54
55 \newcommand{\pkg}[1]{%
56 \textsf{#1}}
57 \newcommand{\opt}[1]{%
58 \texttt{#1}}
59 \newcommand{\email}[1]{%
60 \texttt{#1}}
61 \newcommand{\biblatexSecPage}[2]{%
62 (section #1; page #2)}
63
64 \bibliography{gcite}
65 \begin{document}
66 \DocInput{gcite.dtx}
67 \end{document}
68 %</driver>
69 %\fi
70 %\maketitle
71 %\begin{abstract}
72 %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.
73 %\end{abstract}
74 %
75 %\tableofcontents
76 %
77 %\section{Introduction}
78 %
79 %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.
80 %
81 %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.
82 %
83 %The package can also deal with multi-key citations, as with the traditional \LaTeX\ |\cite| command\cite{opcit,AGRIP}.
84 %
85 %\section{Prerequisites}
86 %
87 %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.
88 %
89 %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}.
90 %
91 %\begin{enumerate}
92 %\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).
93 %
94 %\item Move your |\bibliography| command to the document's preamble (e.g. directly before |\begin{document}|).
95 %
96 %\item Remove the |\bibliographystyle| command.
97 %
98 %\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.
99 %\end{enumerate}
100 %
101 %\section{Usage}
102 %
103 %\DescribeMacro{\usepackage\{gcite\}} To use the \pkg{gcite} package, simply load it. There is only one package option, detailed in section~\ref{sec:pkgopt}.
104 %
105 %All of your citation commands will then be overridden with the new behaviour (even those with non-breaking spaces before them, as is customary for citations in \LaTeX\ documents).
106 %
107 %\subsection{Recommended Citation Style}
108 %
109 %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.
110 %
111 %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.
112 %
113 %\subsection{Multi-Key Citations}
114 %
115 %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).
116 %
117 %\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.
118 %
119 %\subsection{Citations Within Footnotes}
120 %
121 %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.
122 %
123 %\subsection{Reverting to the Standard Behaviour}
124 %
125 %It is possible to revert to the standard \LaTeX/\BibTeX\ citation behaviour. Two methods are provided (to cater for global and local reversion).
126 %
127 %\subsubsection{The \opt{normalcite} Option\label{sec:pkgopt}}
128 %
129 %\DescribeMacro{normalcite} Simply specify the \opt{normalcite} option when loading \pkg{gcite} and the standard behaviour will be restored for all citations in your document.
130 %
131 %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.
132 %
133 %\subsubsection{One-Off Citations in the Standard Style}
134 %
135 %\DescribeMacro{\origcite\{\}} If you wish to make relatively few citations in the standard, non-footnote 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.
136 %
137 %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.
138 %
139 %\section{Customisation}
140 %
141 %There are a few customisation options provided by the \pkg{gcite} package. They allow some control over the way that citations are presented.
142 %
143 %\subsection{Multi-Key Item Separator}
144 %\label{sec:customisation:multi}
145 %
146 %\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.
147 %
148 %\gciteitemsep{ \textbullet\ }
149 %\begin{verbatim}
150 %\gciteitemsep{ \textbullet\ }
151 %\end{verbatim}
152 %
153 %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}.
154 %
155 %\subsection{Footnote Citation Separators}
156 %\label{sec:customisation:foot}
157 %
158 %\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.
159 %
160 %In this example, we redefine only the pre-citation text separator.
161 %
162 %\gcitefootpresep{: }
163 %\begin{verbatim}
164 %\gcitefootpresep{: }
165 %\end{verbatim}
166 %
167 %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.
168 %
169 %\gcitefootpresep{ (}
170 %\gcitefootpostsep{)}
171 %\begin{verbatim}
172 %\gcitefootpresep{ (}
173 %\gcitefootpostsep{)}
174 %\end{verbatim}
175 %
176 %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}.}.
177 %
178 %\printbibliography[heading=bibnumbered]
179 %\appendix
180 %\section{Help for Newcomers to \pkg{biblatex}}
181 %
182 %\begin{quote}
183 %``Don't Panic!''\\
184 %---Douglas Adams, ``The Hitchhiker's Guide to the Galaxy''
185 %\end{quote}
186 %
187 %\gcitefootpresep{}
188 %\gcitefootpostsep{; }
189 %
190 %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.
191 %
192 %\gcitefootpresep{---}
193 %\gcitefootpostsep{}
194 %
195 %\subsection{No Classic \BibTeX\ Custom Styles}
196 %
197 %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}.
198 %
199 %\subsection{More \BibTeX\ Fields Displayed}
200 %
201 %\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}.
202 %
203 %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.
204 %
205 %\subsection{``Missing \$ inserted'' Compilation Error}
206 %
207 %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).
208 %
209 %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.
210 %
211 %\subsection{When Non-US Localisation is Required\ldots}
212 %
213 %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.
214 %
215 %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).
216 %
217 %\subsection{Not All Author Names Displayed in Bibliography}
218 %
219 %This is caused by \pkg{biblatex}'s default style only showing a certain number of author names by default, in contrast to what most people expect to see in the bibliography (a full list). You can solve this by use of the \opt{maxnames} package option for \pkg{biblatex}.
220 %
221 %
222 %
223 %\StopEventually{}
224 %\section{The Code}
225 %\iffalse
226 % \begin{macrocode}
227 %<*gcite.sty>
228 % \end{macrocode}
229 %\fi
230 % Package definition.
231 % \begin{macrocode}
232 \NeedsTeXFormat{LaTeX2e}
233 \ProvidesPackage{gcite}[2009/07/03 1.0.1]
234 \RequirePackage{biblatex}
235 % \end{macrocode}
236 % Define our \opt{normalcite} option and set it to false by default.
237 % \begin{macrocode}
238 \newif\ifgcite@normalcite
239 \gcite@normalcitefalse
240 \DeclareOption{normalcite}{\gcite@normalcitetrue}
241 \ProcessOptions\relax
242 % \end{macrocode}
243 % \subsection{Minor Bits}
244 % Move the traditional |\cite{}| command out of the way.
245 % \begin{macrocode}
246 \let\origcite\cite
247 % \end{macrocode}
248 % Provide a way to customise the separator used between individual cited works.
249 % \begin{macrocode}
250 \providecommand{\gciteitemsep}[1]{\def\gcite@itemsep{#1}}
251 % \end{macrocode}
252 % Default multi-item separator is semicolon with a space following.
253 % \begin{macrocode}
254 \def\gcite@itemsep{; }
255 % \end{macrocode}
256 % 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.
257 % \begin{macrocode}
258 \providecommand{\gcitefootpresep}[1]{\def\gcite@foot@presep{#1}}
259 \providecommand{\gcitefootpostsep}[1]{\def\gcite@foot@postsep{#1}}
260 % \end{macrocode}
261 % Default footnote citation text pre-separator is an em-dash; default post-seperator is literally nothing.
262 % \begin{macrocode}
263 \def\gcite@foot@presep{---}
264 \def\gcite@foot@postsep{}
265 % \end{macrocode}
266 % \subsection{Core Commands}
267 % 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.
268 %
269 % Each individual cited work's details must be treated atomically.
270 % \begin{macrocode}
271 \def\gcite@one#1{\citeauthor{#1}, \citetitle{#1}, \citeyear{#1}}
272 % \end{macrocode}
273 % We need a loop to output the details of each cited work in turn, then display the numerical link(s) at the end.
274 % \begin{macrocode}
275 \def\gcite@core#1#2{%
276 \newif\ifgcite@nfirst
277 \gcite@nfirstfalse%
278 \@for\@c:=#1\do{%
279 \ifgcite@nfirst{\gcite@itemsep}\else\gcite@nfirsttrue\fi%
280 \gcite@one\@c}~\origcite[#2]{#1}}
281 % \end{macrocode}
282 % \subsection{Citation Command Replacement}
283 % If the \opt{normalcite} option was specified, simply emulate the standard \LaTeX\ behaviour (including the non-breaking space).
284 % \begin{macrocode}
285 \ifgcite@normalcite%
286 % (do nothing)
287 \else%
288 % \end{macrocode}
289 % Otherwise, we use the \pkg{gcite} behaviour. As of version 1.0.1 we can handle an option passed in to this command to allow, for example, the document's author to refer the reader to a particular part of the cited document.
290 % \begin{macrocode}
291 \renewcommand{\cite}[2][]{%
292 % \end{macrocode}
293 % 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}.
294 % \begin{macrocode}
295 \ifnum\interlinepenalty=\interfootnotelinepenalty%
296 % \end{macrocode}
297 % 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. We pass the optional argument in as the second argument to our core routine (this is an aesthetic design decision and was made to signify the optional argument to this command being less important than the cite key(s)).
298 % \begin{macrocode}
299 \gcite@foot@presep\gcite@core{#2}{#1}\gcite@foot@postsep%
300 \else%
301 % \end{macrocode}
302 % Otherwise, we're not in a footnote, so create a new one. Again, the optional argument is passed in last. We use |\unskip| so that the author can put spaces (even non-breaking ones) before the citation, as they normally would.
303 % \begin{macrocode}
304 \unskip\footnote{\gcite@core{#2}{#1}}%
305 \fi%
306 }
307 \fi
308 % \end{macrocode}
309 % That's all, folks!
310 %\iffalse
311 % \begin{macrocode}
312 %</gcite.sty>
313 % \end{macrocode}
314 %\fi
315 %\iffalse
316 % \begin{macrocode}
317 %<*gcite.bib>
318 % \end{macrocode}
319 %\fi
320 % \iffalse
321 % \begin{macrocode}
322 @Misc{ makedtx,
323 author = "Nicola Talbot",
324 title = "{makedtx : a Perl script to help create a DTX file from
325 source code}",
326 url = "http://www.ctan.org/tex-archive/support/makedtx/",
327 urldate = {2007-09-02},
328 year = "2005"
329 }
330
331 @Misc{ opcit,
332 author = "Federico Garcia",
333 title = "{opcit (version 2.0) a package for footnote-style
334 bibliographical references}",
335 url = "http://www.ctan.org/tex-archive/macros/latex/contrib/opcit/"
336 ,
337 urldate = {2007-09-02},
338 year = "2006"
339 }
340
341 @Misc{ biblatex,
342 author = "Philipp Lehman",
343 title = "{The biblatex package}",
344 url = "http://www.ctan.org/tex-archive/macros/latex/exptl/biblatex/"
345 ,
346 urldate = {2007-09-02},
347 year = "2006"
348 }
349
350 @Misc{ agrip,
351 author = "Matthew Tylee Atkinson and Sabahattin Gucukoglu",
352 title = "{Accessible Gaming Rendering Independence Possible}",
353 url = "http://www.agrip.org.uk/",
354 month = "05",
355 year = "2003"
356 }
357
358 @InProceedings{ dhiensa2005,
359 author = "Jatinder Dhiensa and Colin Machin and Francesca Smith and
360 Roger Stone",
361 title = "Optimizing the User Environment: Leading Towards an
362 Accessible and Usable Experience",
363 booktitle = "Accessible Design in the Digital World Conference 2005",
364 year = "2005",
365 issn = "1477-9358",
366 location = "Dundee, Scotland",
367 pdf = "paper3.pdf"
368 }
369
370 @InProceedings{ stone2004,
371 author = "R. G. Stone and J. Dhiensa",
372 title = "Proving the validity and accessibility of dynamic
373 web-pages",
374 booktitle = "W4A '04: Proceedings of the 2004 international
375 cross-disciplinary workshop on Web accessibility (W4A)",
376 year = "2004",
377 pages = "45--49",
378 address = "New York, NY, USA",
379 publisher = "ACM Press",
380 doi = "http://doi.acm.org/10.1145/990657.990665",
381 isbn = "1-58113-903-9",
382 pdf = "p45-stone.pdf"
383 }
384 % \end{macrocode}
385 % \fi
386 %\iffalse
387 % \begin{macrocode}
388 %</gcite.bib>
389 % \end{macrocode}
390 %\fi
391 %\Finale
392 \endinput