diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /indexing/authorindex |
Initial commit
Diffstat (limited to 'indexing/authorindex')
-rw-r--r-- | indexing/authorindex/COPYING | 5 | ||||
-rw-r--r-- | indexing/authorindex/NEWS | 42 | ||||
-rw-r--r-- | indexing/authorindex/README | 8 | ||||
-rwxr-xr-x | indexing/authorindex/authorindex | 586 | ||||
-rw-r--r-- | indexing/authorindex/authorindex.pdf | bin | 0 -> 54632 bytes | |||
-rw-r--r-- | indexing/authorindex/authorindex.sty | 131 | ||||
-rw-r--r-- | indexing/authorindex/authorindex.tex | 734 |
7 files changed, 1506 insertions, 0 deletions
diff --git a/indexing/authorindex/COPYING b/indexing/authorindex/COPYING new file mode 100644 index 0000000000..a2960c90c3 --- /dev/null +++ b/indexing/authorindex/COPYING @@ -0,0 +1,5 @@ +The authorindex package is subject to the LaTeX project public +license. You can find a copy of the license here: + + http://www.latex-project.org/lppl.txt + diff --git a/indexing/authorindex/NEWS b/indexing/authorindex/NEWS new file mode 100644 index 0000000000..9eeaee5d5b --- /dev/null +++ b/indexing/authorindex/NEWS @@ -0,0 +1,42 @@ +27 July 2019: + +- The package is no longer maintained. + +August 2008: + +- Describe workaround for bibunits (simplified from Sylwester Arabas's + proposal) + +October 2007 + +- Support names and citation keys longer than 79 characters. Note + that if you used you own bst script (via \authorindexstyle) in the + past, you need to revise that bst script to include additional + separator lines. + +- Bugfix: Use semicolon as pathname separator on Windows + +May 2007 + +- Bugfix: Allow the same BibTeX data base to appear repeatedly in the + LaTeX source. This is hard to avoid for when using chapterbib. + +November 2006: + +- Include an enhancement by Pieter Eendebak for natbib.cfg (part + of the documentation) + +March 2005: + +- Support for authauthor and autheditor fields in BibTeX data base. + These fields serve to provide a consistent spelling of author names + +- Bugfix: When using multiple BibTeX data bases, they will be queried + in the sequence given in the LaTeX source. This is important when + some data bases define @STRINGs used in others. + +October 2004: + +- Bugfix: Gracefully handle spaces in citation commands with multiple + arguments. Previous versions included the space in the key, which + caused the search in the BibTeX data base to fail. diff --git a/indexing/authorindex/README b/indexing/authorindex/README new file mode 100644 index 0000000000..6a7671761b --- /dev/null +++ b/indexing/authorindex/README @@ -0,0 +1,8 @@ +This package allows to create an index of all authors cited in a LaTeX +document. Each author entry in the index contains the pages where +these citations occur. Alternatively, the package can list the labels +of the citations that appear in the references rather than the text +pages. + +The package relies on bibtex being used to handle citations. +Additionally, it requires Perl (version 5 or higher). diff --git a/indexing/authorindex/authorindex b/indexing/authorindex/authorindex new file mode 100755 index 0000000000..6c154a080e --- /dev/null +++ b/indexing/authorindex/authorindex @@ -0,0 +1,586 @@ +#!/usr/bin/env perl +# This file is part of the authorindex package for LaTeX + BibTeX. +# Version: 10. August 2008 + +use warnings 'all'; +use strict; + +# configuration: apart from the command to invoke perl above you might want to +# change: + +my $bstenv="BSTINPUTS"; # Environment Variable holding .bst search path +my $bibenv="BIBINPUTS"; # Env Variable holding search path for BibTeX databases +my $tmp="_autidx_"; # Name base for temporary files +my $cwdpath="."; # Directory where files are generated +my $pathsep=($^O eq "MSWin32") ? ';' : ":"; # Seperator between paths in a list + +# This script takes LaTeX .aux files as input. It extracts all citations made +# with page number information. These, together with the bibliography data base +# extracted from the input and a .bst file are processed by bibtex to get a +# file that associates each citation label with corresponding authors. Together +# with the knowledge of which work is cited on which page, this is used to +# compute which author is cited on which page. This information is written to +# the output in form suitable to be included in a LaTeX document. +# Alternatively, the script can also extract the label that appears in the +# references for each work instead of the pages. Also, output for further +# processing by makeindex can be generated instead of a 'ready' LaTeX file. + +# examine command line for options + +my %opt; # hash to contain options found +use Getopt::Std; +getopts('dhikpr',\%opt); + +# handle -h option: a short description of the script. + +exists $opt{'h'} && die <<END; +Usage: $0 [-d] [-h] [-i] [-k] [-p] [-r] [filename ...] + +-d generate additional statistical information as comments +-i generate file (with extension .ain) suitable as input for makeindex +-k keep auxiliary bibliography style file $tmp.bst after script finishes +-h print this help and exit +-r suppresses automatic inclusion of .aux generated by \\include-ed files +-p send result to standard output + +Any number of file names can be given. If none is given, input is read from +standard input. Otherwise, all files specified are read, after the extension +.aux has been appended to their name where necessary. +END + +# Make sure that all input files get .aux extension. + +grep(s/$/\.aux/,grep(!/\.aux$/,@ARGV)); +my @SAVEARGV=@ARGV; + +my $usenum=0; # default: put page numbers into index +my $PageTypeOrder="rRnAa"; # default order of number types +my $altedit="'skip\$"; # no editors if no authors present +my $addedit="'skip\$"; # no editors if authors present + +my $citationcount=0; # used for statistics +my $workscount=0; +my $explicits=0; +my $authorcount=0; + +my $miniindex=0; # flag: is 1 if mini-index is requested +my $nocompress=0; # flag: is 1 if page range compression is prohibited + +my @bib; # collect .bib-file names +my %biboccured; # collect .bib-file names +my %pnlist; # collect occuring pages/bib.numbers as keys of hash + +my $editors=0; # number: 0 no editors; 1 editors if no authors + # 2: editors whenever present +my $nameformat=""; # string to format/sort names +my $maxnames=999; # max. number of author names per entry +my $truncnames=999; # how many authors to take if max number is exceeded +my $labeltype="labels"; # wether bibliography labels or pages are indexed + +my %Lab2Pag; # for each label gives array of pages where work cited +my %Lab2Num; # for each label give its bibliography number +my %Lab2Bib; # ditto, but for occurrence in bibliography +my %Aut2Pag; # for each author gives array of pages cited/in bilio. +my %Aut2Bib; # ditto, but only occurrence in bibliography +my %Aut2Lab; # list of BibTeX entry labels an author occurs in +my %Aut2First; # list of all 1st authors to which author was coauthor +my %LeadAutPag; # author -> hash marking pages with work author is 1st + +my %printname; # sort-key -> printed representation of author +my %plainname; # sort-key -> author name + +my %PageTypeOrder; # Page type code -> number giving relative order +my %PageOrder; # page string -> array used to sort pages + +my $see=""; # string to separate other and first author, or undef. +my $bst=""; # name of BibTeX program to extract author names +my $output=""; # name of file to which author index is written +my $twoabbrev=""; # string to append to page for 2 subsequent pages +my $also=""; # string to cross-refer to first authors +my $alsosep=""; # seperator for referenced first authors + +my $useaibibcite; # flag: watch for \aibibcite, but not for \bibcite. + +# scan input files and +# - build the file later to be processed by BibTeX, +# - generate a temporary bibtex database of the explicit author names given, +# - assemble for each citation the page where it was referenced and +# - look for data base specification, output file name, and so on. + +open(AUXFILE,">$tmp.aux") || die "Can't open temporary file $tmp.aux\n"; +open(BIBFILE,">$tmp.bib") || die "Can't open temporary file $tmp.bib\n"; + +while(<>){ + if(/^\\citationpage\{\s*([^{ ]+)\s*\}\{(.+)\}$/){ + $citationcount++; # used for statistics only. + $workscount++ unless ($1 eq '*') or (exists $Lab2Pag{$1}) + or (exists $Lab2Bib{$1}) or (exists $Lab2Num{$1}); + $pnlist{$2}=""; + push @{$Lab2Pag{$1}},$2; + print AUXFILE "\\citation{$1}\n"; + }elsif(/^\\aibibcite\{([^{]+)\}\{(.+)\}$/){ + $workscount++ unless ($1 eq '*') or (exists $Lab2Pag{$1}) + or (exists $Lab2Bib{$1}) or (exists $Lab2Num{$1}); + $pnlist{$2}=""; + push @{$Lab2Num{$1}},$2; + print AUXFILE "\\citation{$1}\n" if $usenum; + # using \aibibcite implies we want to ignore \bibcite. For this to + # work, in the .aux files, the first \aibibcite must appear before any + # \bibcite. + $useaibibcite="yes"; + }elsif(/^\\bibcite\{([^{]+)\}\{(.+)\}$/){ + unless($useaibibcite){ + $workscount++ unless ($1 eq '*') or (exists $Lab2Pag{$1}) + or (exists $Lab2Bib{$1}) or (exists $Lab2Num{$1}); + $pnlist{$2}=""; + push @{$Lab2Num{$1}},$2; + print AUXFILE "\\citation{$1}\n" if $usenum; + } + }elsif(/^\\bibpage\{([^{]+)\}\{(.+)\}$/){ + $workscount++ unless (exists $Lab2Pag{$1}) + or (exists $Lab2Bib{$1}) or (exists $Lab2Num{$1}); + $pnlist{$2}=""; + push @{$Lab2Bib{$1}},$2; + print AUXFILE "\\citation{$1}\n"; + }elsif(/^\\aiexplicit\{(.+)\}\{(.+)\}$/ and !$usenum){ + # above: page number might not contain '}{' + print BIBFILE "\@MISC{$tmp$explicits,author=\"$1\"}\n"; + $pnlist{$2}=""; + push @{$Lab2Pag{"$tmp$explicits"}},$2; + print AUXFILE "\\citation{$tmp$explicits}\n"; + $explicits++; + }elsif(/^\\bibdata\{(.+)\}$/){ + # keep the order of data base files, but remove duplicates; + # BibTeX complains about them. + my $bibdb; + for $bibdb (split(",",$1)){ + push @bib, $bibdb unless $biboccured{$bibdb}; + $biboccured{$bibdb}=1; + } + }elsif(/^\\aistyle\{(.+)\}$/){ + warn "Multiple \\authorindexstyle\n" if $bst && ($bst ne $1); + $bst=$1; + }elsif(/^\\aioptions\{(.*)\}$/){ + ($editors,$nameformat,$maxnames,$truncnames,$labeltype)=split /\|/,$1; + $usenum|=($labeltype eq "labels"); + if($editors>0){ + $altedit="{ peditor format }"; + $addedit=$altedit if $editors==2; + } + }elsif(/^\\aifilename\{(.+)\}$/){ + warn "Warning: Multiple authorindices\n" if $output; + $output=$1; + }elsif(/^\\\@input\{(.+)\}$/){ + push(@ARGV,$1) unless exists $opt{'r'}; + }elsif(/^\\pagetypeorder\{([rRaAn]+)\}$/){ + $PageTypeOrder=$1; + }elsif(/^\\aiseestring\{(.+)\}$/){ + $see=$1; + }elsif(/^\\aialsostrings\{(.+)\}\{(.+)\}$/){ + $also=$1; + $alsosep=$2; + }elsif(/^\\aitwostring\{(.+)\}$/){ + $twoabbrev=$1; + }elsif(/^\\aiinbibflag$/){ + $miniindex=1; + }elsif(/^\\ainocompressflag$/){ + $nocompress=1; + } +} + +close BIBFILE; + +# output can go to stdout or a filename found in the input files. + +$output || die "You have to include .aux file produced by .tex file containing \\begin{document}\nin the argument list and you have to \\usepackage{authorindex}!\n"; +$output="-" if exists $opt{'p'}; + +# We need at least one BibTeX database + +push @bib, $tmp if($explicits); + +my $bibfiles=join(",",@bib) + || die "You must specify at least one BibTeX database\n"; +print AUXFILE "\\bibdata{$bibfiles}\n"; + +$see && $also && die "\\aisee and \\aialso are mutually exlusive!\n"; + +# if the user hasn't explicitly given a .bst style for formatting author names, +# we generate our own based on the style options found in the input files. + +unless($bst){ + my @nameformat=split /;/,$nameformat; + my ($printkey,$namefmtcmd)=("cite\$ write\$ termline\n",""); + for (@nameformat){ + my ($namerep,$sortrep)=split /:/; + $sortrep=$namerep unless $sortrep; + $namefmtcmd.= + "duplicate\$ names swap\$ \"$namerep\" format.name\$ " . + "write\$ termline\n" . + "duplicate\$ names swap\$ \"$sortrep\" format.name\$ " . + "purify\$ \"u\" change.case\$ write\$ termline\n$printkey"; + $printkey="termline\n"; + } + + $ENV{$bstenv}="$cwdpath$pathsep" . (exists $ENV{$bstenv} ? $ENV{$bstenv} : ""); + $bst=$tmp; + open(BSTFILE,">$bst.bst") || die "Can't open $bst.bst\n"; + print BSTFILE <<END; # Now comes the BibTeX programm inlined... +% Temporary file generated by $0 +entry{author editor authauthor autheditor}{}{} +strings{names} integers{numnames} +function{prefersecond} % return second argument if non-empty +{ duplicate\$ empty\$ % return first argument otherwise + 'skip\$ %' + { swap\$ } + if\$ + pop\$ +} +function{pauthor}{ author authauthor prefersecond } +function{peditor}{ editor autheditor prefersecond } +function{termline}{ newline\$ "%" write\$ newline\$ } +function{format} +{ duplicate\$ empty\$ % field present? + { pop\$ } % no: do nothing but cleanup + { duplicate\$ 'names := %'memorise namelist in variable "names" + num.names\$ duplicate\$ + #$maxnames > % too many names in list? + { pop\$ #$truncnames } % yes, truncate. + 'skip\$ %' no, keep them all + if\$ + 'numnames := %'save number of names + #0 % start index + { duplicate\$ numnames < } % test for "while\$" + { #1 + % next name + duplicate\$ names swap\$ % get name list and index + "{ll}" format.name\$ % format curr. name + "others" = % et al part? + 'skip\$ %' yes, do not output + { $namefmtcmd } % no: format all + if\$ + } while\$ pop\$ % loop until index is 0 + } + if\$ +} +function{default.type}{pauthor format pauthor empty\$ $altedit $addedit if\$ } +function{article}{default.type} function{book}{default.type} +function{booklet}{default.type} function{inbook}{default.type} +function{incollection}{default.type} function{inproceedings}{default.type} +function{conference}{default.type} function{manual}{default.type} +function{mastersthesis}{default.type} function{misc}{default.type} +function{phdthesis}{default.type} function{proceedings}{default.type} +function{techreport}{default.type} function{unpublished}{default.type} +read iterate{call.type\$} +END + # ... and here comes perl again. + close BSTFILE; +} + +# Now we have decided on our .bst file and can finish the temporary .aux file +# we prepared for BibTeX. + +print AUXFILE "\\bibstyle{$bst}\n"; +close AUXFILE; + +# if we have written to the temporary database, make sure BibTeX can find it. + +$ENV{$bibenv}="$cwdpath$pathsep" . (exists $ENV{$bibenv} ? $ENV{$bibenv} : "") if $explicits; + +# We now give BibTeX all the citation labels. In return we get a file whose +# lines in turn contain an author name and a label of a work of that author. +# The format the author names are given are determined by the BibTeX style file +# $bst.bst. + +print STDERR `bibtex $tmp`; +die "BibTeX error. Aborting leaving all temporary files $tmp.*\n" if $?; + +# if things went well, we can delete all these temporary files made for BibTeX. +# The generated .bst file is kept if the user wishes so (-k option). + +unlink "$bst.bst" if ($bst eq $tmp && !(exists $opt{'k'})); +unlink "$tmp.aux","$tmp.bib"; + +# Decide wether pages or citation labels go to the index + +my %Lab2Ent=%Lab2Pag; +if($usenum){ + %Lab2Ent=%Lab2Num; + %Lab2Bib=(); +}else{ + %Lab2Num=(); +} + +# We have now labels associated with page numbers and labels associated with +# author names (in the file generated by the BibTeX run). Now we can bring +# together the previous two main steps and compute for each author the pages +# where she is cited. In draft mode, we also remember for each author the +# labels of her works and the pages where these works are cited. + +my ($firstauthor,$firstsortname,$Lab,$PrevLab)=("","","",""); +open(BIBFILE,"$tmp.bbl") || die "Can't open $tmp.bbl\n"; +my $author; +while($author=&readtosep()){ + map s/[\[\]]//g, $author; + my $sortname=&readtosep(); + my $LabOrEmpty=&readtosep(); + if($LabOrEmpty){ + $PrevLab=$Lab; + $Lab=$LabOrEmpty; + } + my $printname=$author; + if($Lab ne $PrevLab){ + @{$LeadAutPag{$author}}{@{$Lab2Ent{$Lab}}}="" if exists $Lab2Ent{$Lab}; + @{$LeadAutPag{$author}}{@{$Lab2Ent{'*'}}}="" if exists $Lab2Ent{'*'}; + @{$LeadAutPag{$author}}{@{$Lab2Bib{$Lab}}}="" if exists $Lab2Bib{$Lab}; + $firstauthor=$author; + $firstsortname=$sortname; + }else{ + ${$Aut2First{$sortname}}{$firstsortname}=""; + if($see){ + $printname="{$author}$see\\aifirst{$firstauthor}"; + $sortname="$sortname$see$firstsortname"; + } + } + @{$Aut2Pag{$printname}}{@{$Lab2Ent{$Lab}}}="" if exists $Lab2Ent{$Lab}; + @{$Aut2Pag{$printname}}{@{$Lab2Ent{'*'}}}="" if exists $Lab2Ent{'*'}; + @{$Aut2Pag{$printname}}{@{$Lab2Bib{$Lab}}}="" if exists $Lab2Bib{$Lab}; + @{$Aut2Bib{$printname}}{@{$Lab2Bib{$Lab}}}="" if exists $Lab2Bib{$Lab}; + push @{$Aut2Lab{$printname}},$Lab if (exists $opt{'d'}) and $LabOrEmpty; + $printname{$sortname}=$printname; + $plainname{$sortname}=$author; +} +close BIBFILE; +unlink "$tmp.blg","$tmp.bbl"; + +# Last not least, output the results, properly sorted if needed. + +open(AIFILE,">$output") || die "Can't create author index file $output\n"; + +# convert page type order into numerical values +my ($i,$page); +$PageTypeOrder{$i}=length($PageTypeOrder) while($i=chop $PageTypeOrder); +# create table that relates page to page order info +for $page (keys %pnlist){ + $PageOrder{$page}=&parse_pagenumber($page); +} + +if($also){ + my $coauthorname; + for $coauthorname (keys %Aut2First){ + my @namelist; + my $sortname; + for $sortname (sort keys %{$Aut2First{$coauthorname}}){ + push @namelist, $printname{$sortname}; + } + # we rely on the fact that " " is alphabetically first, so that + # $justbehind will end up directly after $coauthorname + my $justbehind=$coauthorname." "; + my $pseudoname=$also.join($alsosep, @namelist); + $printname{$justbehind}=$pseudoname; + $plainname{$justbehind}=$pseudoname; + } +} + +if(exists $opt{'i'}){ + # generate file for makeindex: leave the work for makeindex. + my $name; + for $name (keys %printname){ + my $author=$printname{$name}; + my $page; + for $page (keys %{$Aut2Pag{$author}}){ + print AIFILE "\\indexentry{$name\@$author}{$page}\n"; + } + } +}else{ + # sort result, throw away duplicate page numbers and generate LaTeX file. + print AIFILE "\\begin{theauthorindex}\n"; + my ($prevfirstchar,$prevplain,$name)=("","",""); + for $name (sort keys %printname){ + my $thisfirstchar=substr($name,0,1); + if($thisfirstchar ne $prevfirstchar){ + print AIFILE "\\indexspace\n" if $prevfirstchar; + $prevfirstchar=$thisfirstchar; + } + my $author=$printname{$name}; + my $plain=$plainname{$name}; + my $rep=$author; + if($Aut2Lab{$author}){ + print AIFILE "% @{$Aut2Lab{$author}}\n" if(exists $opt{'d'}); + $rep=($plain eq $prevplain) ? "\\airep$author" : "\\aitop$author" + if $plain ne $author; + $prevplain=$plain; + $authorcount++; + } + print AIFILE "\\item[$rep]"; + $Aut2Bib{$author}={} unless exists $Aut2Bib{$author}; + $LeadAutPag{$author}={} unless exists $LeadAutPag{$author}; + my %b2p=%{$Aut2Bib{$author}}; + my %lp=%{$LeadAutPag{$author}}; + my %pagerep; + my $page; + for $page (keys %{$Aut2Pag{$author}}){ + my $prep=$page; + $prep="\\aifirstpage{$prep}" if exists $lp{$page}; + $prep="\\aibibpage{$prep}" if exists $b2p{$page}; + $pagerep{$page}=$prep; + } + my $res=&compressed_pages($Aut2Pag{$author},\%pagerep); + print AIFILE " \\aipages{$res}\n"; + } + print AIFILE "\\end{theauthorindex}\n"; + if(exists $opt{'d'}){ # in draft mode, include some statistics + print AIFILE "%\n% $citationcount citations "; + print AIFILE "of $workscount distinct works\n"; + print AIFILE "% $explicits times \\aimention\n" if $explicits; + print AIFILE "% $authorcount different authors\n"; + } +} +close AIFILE; + +# merge mini indices into the .bbl-Files if it was requested. + +if($miniindex){ + map s/aux$/bbl/,@SAVEARGV; + my $file; + for $file (@SAVEARGV){ + open(BBLINPUT,$file) || next; + open(BBLHELP,">$tmp.bbl") || die "Can't create temp file $tmp.bbl\n"; + my $currlabel=""; + while(<BBLINPUT>){ + if(/\\bibitem(\[.*\])*\{(.*)\}|\\end\{thebibliography\}/){ + if($currlabel){ + my $pagelist=&pages_for_label($currlabel); + print BBLHELP "\\bibindex{$pagelist}\n"; + } + $currlabel=$2; + print BBLHELP "$_"; + }elsif(/\\bibindex\{(.*)\}/){ + if($currlabel){ + my $pagelist=&pages_for_label($currlabel); + print BBLHELP "$`\\bibindex{$pagelist}$'"; + } + $currlabel=""; + }else{ + print BBLHELP "$_" if "$_" ne "\n"; + } + } + close BBLHELP; + close BBLINPUT; + rename "$tmp.bbl","$file" || die "Can't replace old $file\n"; + } +} + +# auxiliary functions + +# convert roman numeral string to integer + +sub romanvalue +{ + local($_)=shift; tr/IVXLCDM/ivxlcdm/; + my %romandigits = ("i", 1, "v", 5, "x", 10, "l", 50, + "c", 100, "d", 500, "m", 1000); + my ($i,$sum,$prev)=("",0,1); + while($i=chop){ + my $this=$romandigits{$i}; + $sum=$sum+(($this<$prev) ? -$this : $this); + $prev=$this; + } + return $sum; +} + +# convert letter to numeric value + +sub alphavalue +{ + local($_)=@_; tr/A-Z/a-z/; + return ord($_)-ord("a"); +} + +# split page number in components and replace each component by a number for +# the page type and the page number as an integer. + +sub parse_pagenumber +{ + local($_)=@_; + my $res=""; + while($_){ + s/^[^\\A-Za-z0-9]*//; + if(exists $PageTypeOrder{'n'} && s/(^\d+)//){ + $res.="$PageTypeOrder{'n'}".sprintf "%0.6d",$1; + }elsif(exists $PageTypeOrder{'R'} && + s/^\\uppercase\s*\{([ivxlcdm]+)\}//){ + $res.="$PageTypeOrder{'R'}".sprintf "%0.4d",&romanvalue($1); + }elsif(exists $PageTypeOrder{'R'} && s/(^[IVXLCDM]+)//){ + $res.="$PageTypeOrder{'R'}".sprintf "%0.4d",&romanvalue($1); + }elsif(exists $PageTypeOrder{'A'} && s/(^[A-Z])//){ + $res.="$PageTypeOrder{'A'}".sprintf "%0.2d",&alphavalue($1); + }elsif(exists $PageTypeOrder{'r'} && s/(^[ivxlcdm]+)//){ + $res.="$PageTypeOrder{'r'}".sprintf "%0.4d",&romanvalue($1); + }elsif(exists $PageTypeOrder{'a'} && s/(^[a-z])//){ + $res.="$PageTypeOrder{'a'}".sprintf "%0.2d",&alphavalue($1); + }else{ + s/^.//; + } + } + return $res; +} + +# test wether 2 pages are subsequent + +sub a_follows_b +{ + my ($i,$j)=@PageOrder{@_}; + $i++; + return($i eq $j); +} + +# make a sorted, maybe compressed, list of pages + +sub compressed_pages +{ + my ($A,$B)=@_; + my %pages=%{$A}; + my %pagerep=%{$B}; + my ($prevpage,$pendrep,$res,$pagepending,$page)=("","","","",""); + for $page (sort { $PageOrder{$a} cmp $PageOrder{$b} } keys %pages){ + # handle compression of page ranges. At the moment, we + # also compress ranges that might be displayed in different faces + my $pagerep=(exists $pagerep{$page}) ? $pagerep{$page} : $page; + if($prevpage){ + if(!$nocompress and &a_follows_b($prevpage,$page)){ + $pendrep=$pagepending ? "--$pagerep" + : ($twoabbrev ? "$twoabbrev" : ", $pagerep"); + $pagepending=1; + }else{ + $res.=($pagepending ? "$pendrep" : "").", $pagerep"; + $pagepending=0; + } + }else{ + $res.="$pagerep"; + } + $prevpage=$page; + } + $res.="$pendrep" if $pagepending; + return $res; +} + +sub pages_for_label +{ + my ($label)=@_; + if(exists $Lab2Pag{$label}){ + my (%pages,%empty); + @pages{@{$Lab2Pag{$label}}}=""; + return &compressed_pages(\%pages,\%empty); + } + return ""; +} + +sub readtosep +{ + my $sum=""; + while(<BIBFILE>){ + return $sum if(/^%$/); + chop; s/%$//; + $sum.=$_; + } +} diff --git a/indexing/authorindex/authorindex.pdf b/indexing/authorindex/authorindex.pdf Binary files differnew file mode 100644 index 0000000000..02f3c361bf --- /dev/null +++ b/indexing/authorindex/authorindex.pdf diff --git a/indexing/authorindex/authorindex.sty b/indexing/authorindex/authorindex.sty new file mode 100644 index 0000000000..0caeaed658 --- /dev/null +++ b/indexing/authorindex/authorindex.sty @@ -0,0 +1,131 @@ +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{authorindex}[2005/03/22 make index of authors cited in a work] +% \ainame and \aipages determine the format of the author name and the page +% list, respectively, and are to be \renewcommand-ed explicitly by the user. +% \aibibpage and \aifirstpage are styles for pages where works appear in the +% references and where the author is the first author of the work, respectively +\def\ainame#1{#1} +\def\aitop#1{#1} +\def\airep#1{#1} +\def\aifirst#1{#1} +\def\aipages#1{#1} +\def\aibibpage#1{#1} +\def\aifirstpage#1{#1} +% The following stuff can be changed via options to \usepackage +\newcommand\aisize{} +\def\@ainamefmt{} +\def\@aieditors{0} +\def\@aiwhat{pages} +% These Options will be handled directly by LaTeX +\DeclareOption{small}{\renewcommand\aisize{\small}} +\DeclareOption{normal}{\renewcommand\aisize{\normalsize}} +% These Options will go to the perl script and be used to build the .bst file. +\let\aioptions\@gobble +\DeclareOption{editors}{\renewcommand\@aieditors{2}} +\DeclareOption{avoideditors}{\renewcommand\@aieditors{1}} +\DeclareOption{onlyauthors}{\renewcommand\@aieditors{0}} +\DeclareOption{fullname}{\renewcommand\@ainamefmt{{vv }{ll}{, ff}{, jj}}} +\DeclareOption{lastname}{\renewcommand\@ainamefmt{{vv }{ll}}} +\DeclareOption{firstabbrev}{\renewcommand\@ainamefmt{{vv }{ll}{, f.}{, jj}}} +\DeclareOption{all}{\def\@aiwhich{9999}\def\@aitrunc{9999}} +\DeclareOption{onlyfirst}{\def\@aiwhich{1}\def\@aitrunc{1}} +\DeclareOption{miniindex}{\AtBeginDocument{% + \if@filesw\immediate\write\@auxout{\string\aiinbibflag}\fi}}% +\DeclareOption{nocompress}{\AtBeginDocument{% + \if@filesw\immediate\write\@auxout{\string\ainocompressflag}\fi}}% +\DeclareOption{pages}{\renewcommand\@aiwhat{pages}} +\DeclareOption{biblabels}{\renewcommand\@aiwhat{labels}} +\DeclareOption{withbib}{\AtBeginDocument{% + \let\@aiobibitem=\@bibitem\let\@aiolbibitem=\@lbibitem% + \def\@lbibitem[#1]#2{\@aiolbibitem[#1]{#2}% + \if@filesw{\protected@write\@auxout{} + {\string\bibpage{#2}{\theaipage}}}\fi\ignorespaces}% + \def\@bibitem#1{\@aiobibitem{#1}% + \if@filesw{\protected@write\@auxout{} + {\string\bibpage{#1}{\theaipage}}}\fi\ignorespaces}}}% +\ExecuteOptions{normal,fullname,all} +\ProcessOptions +% make sure options and filename are transfered to the perl script. +\expandafter\AtBeginDocument{\if@filesw\immediate{% + \write\@auxout{% + \string\aioptions{\@aieditors|\@ainamefmt|\@aiwhich|\@aitrunc|\@aiwhat}}% + \write\@auxout{\string\aifilename{\jobname.ain}}}% + \fi% + \def\aipagetypeorder{\@notprerr}% Generate error messages when used outside + \def\aimaxauthors{\@notprerr}% preamble. + \def\authorindexstyle{\@notprerr}% + \def\aisee{\@notprerr}% + \def\aialso{\@notprerr}% + \def\aitwosuffix{\@notprerr}% + \def\ainamefmt{\@notprerr}} +% Define commands to be put in the .aux file and only used by the perl script. +\let\pagetypeorder\@gobble +\let\aiseestring\@gobble +\let\aitwostring\@gobble +\let\ainocompressflag\relax +\let\aiinbibflag\relax +\let\aistyle\@gobble +\let\citationpage\@gobbletwo +\let\bibpage\@gobbletwo +\let\aiexplicit\@gobbletwo +\let\aifilename\@gobble +\let\aialsostrings\@gobbletwo +\let\aibibcite\@gobbletwo +% By default, the numbers that appear in the index are the same that appear on +% the pages. In case this does not suffice for everybody (for example, in a 2 +% volume book, one might want the volume number appear in the index, but not +% in the page numbering) one can redefine this: +\def\theaipage{\thepage} +% determine the relative order of different numbering types (roman, arabic,...) +\def\aipagetypeorder#1{\AtBeginDocument{% + \if@filesw\immediate\write\@auxout{\string\pagetypeorder{#1}}\fi}}% +% determine string by which first author is cross referenced +\def\aisee#1{\AtBeginDocument{% + \if@filesw\immediate\write\@auxout{\string\aiseestring{#1}}\fi}}% +% determine string by which first authors are cross referenced +\def\aialso#1#2{\AtBeginDocument{% + \if@filesw\immediate\write\@auxout{\string\aialsostrings{#1}{#2}}\fi}}% +% determine string for abbreviation of two subsequent pages +\def\aitwosuffix#1{\AtBeginDocument{% + \if@filesw\immediate\write\@auxout{\string\aitwostring{#1}}\fi}}% +% determines representation of miniindices +\def\aibibindex#1{\{\textbf{#1}\}} +\def\bibindex#1{\ifx\\#1\\\@bsphack\@esphack\else\aibibindex{#1}\fi} +% \authorindexstyle{x} writes \aistyle{x} to the .aux-file. x later will be +% used to select the x.bst as the bibstyle used to generate the author list +% from the database (overriding the generated .bst file). +\def\authorindexstyle#1{\AtBeginDocument{% + \if@filesw\immediate\write\@auxout{\string\aistyle{#1}}\fi}} +% determine formating and order of names +\def\ainamefmt#1{\def\@ainamefmt{#1}} +% Allow for other max. number of authors apart from 1 and 9999. +% First Argument lets us determine to how many authors to truncate the list. +\def\aimaxauthors{\@ifnextchar[\@aitruncmaxauthors\@aimaxauthors} +\def\@aitruncmaxauthors[#1]#2{\def\@aitrunc{#1}\def\@aiwhich{#2}} +\def\@aimaxauthors#1{\def\@aitrunc{#1}\def\@aiwhich{#1}} +% \aicite behaves similar to cite, but additionally writes for each key given +\def\@aicitey#1{% + \@for\@citeb:=#1\do + {\protected@write\@auxout{}% + {\string\citationpage{\@citeb}{\theaipage}}}} +\def\@aicitex[#1]#2{\@citex[#1]{#2}\@aicitey{#2}} +% \aicite behaves similar to cite, but additionally writes for each key given +\DeclareRobustCommand\aicite{% + \@ifnextchar [{\@tempswatrue\@aicitex}{\@tempswafalse\@aicitex[]}}% +\let\@oldnocite=\nocite +\def\ainocite#1{\@aicitey{#1}\@oldnocite{#1}} +\def\aionly{\@aicitey} +% \aimention gets authors BibTeX author name format to be included in the +% author index without having any reference of a work of that author. +\def\aimention#1{\@bsphack% + \protected@write\@auxout{}{\string\aiexplicit{#1}{\theaipage}}\@esphack} +% include author index +\newcommand\printauthorindex{\@input@{\jobname.ain}} +% the theauthorindex environment +\newenvironment{theauthorindex}{% + \raggedright% + \setlength{\leftskip}{1em}% + \setlength{\parindent}{-1em}% + \def\item[##1]{\par\hspace{0mm}\ainame{##1}} + \aisize}{\par} +\endinput diff --git a/indexing/authorindex/authorindex.tex b/indexing/authorindex/authorindex.tex new file mode 100644 index 0000000000..69dc94c637 --- /dev/null +++ b/indexing/authorindex/authorindex.tex @@ -0,0 +1,734 @@ +\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em + T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}} +% \BibTeX command above has been stolen from \cite{Patashnik88a} +\documentclass[a4paper]{article} + +\usepackage[T1]{fontenc} +\usepackage{textcomp} +\usepackage{charter} +\usepackage[scaled=0.88]{beramono} +\usepackage{microtype} + +\renewcommand{\labelitemi}{\textbullet} +\newcommand{\package}[1]{\texttt{#1}} +\newcommand{\authorindex}{\package{authorindex}} +\newcommand{\mkindex}{\package{makeindex}} +\newcommand{\perl}{\texttt{perl}} + +\newcommand{\file}[1]{\texttt{#1}} +\newcommand{\fnext}[1]{\file{.#1}} +\newcommand{\aisty}{\file{authorindex.sty}} + +\newcommand{\cmdline}[1]{\texttt{#1}} +\newcommand{\option}[1]{\cmdline{#1}} +\newcommand{\aiperl}{\cmdline{authorindex}} +\newcommand{\bibtex}{\cmdline{bibtex}} + +\newcommand{\ltxinp}[1]{\texttt{\string#1}} + +\renewcommand\descriptionlabel[1]{\hspace\labelsep\normalfont\texttt{#1}} + +\title{The \authorindex\ Package} +\author{Andreas Wettstein\\\texttt{wettstae@gmail.com}} +\date{August 2008} + +\begin{document} + +\maketitle + +\begin{abstract} + The \authorindex\ package lists all authors cited in a \LaTeX\ document from + the \ltxinp{\cite} entries and their associated \fnext{bib} bibliography + files. It will not run with bibliographical entries (\ltxinp{\bibitem}) + explicitly typed into the document. Each author entry in the generated list + contains the pages where these citations occur. Alternatively, the package + can list the labels of the citations that appear in the references rather + than the text pages. The package requires \perl\ (version 5 or higher) to run + an auxiliary script and \BibTeX. The package can be used by itself or as a + preprocessor for \mkindex. It can produce separate indices and mini indices, + which are merged in the bibliography. The package can run under Unix, + Windows, or MS-DOS. The \authorindex\ package is compatible with the standard + bibliographical styles distributed with \LaTeX\ and with \package{hyperref}. + With the small patches listed here, it will also run with the + \package{chapterbib}, \package{chicago}, \package{harvard}, and + \package{natbib} bibliographical style packages. +\end{abstract} + + +\section{Installation} + +The \authorindex\ package consists of the \LaTeX\ style file \aisty\ and the +\perl\ script \aiperl. It needs \LaTeX, \BibTeX\ \cite{Patashnik88a} and +\perl\ (version 5 or better) to run. + +To install the package, move \aisty\ to a place where \LaTeX\ looks for its +style files. Unix: The \perl\ script \aiperl\ must be moved to a place in your +executable path and be given execution permission. You may need to modify the +path to the \perl\ binary that appears in the first line of the script \aiperl, +replacing \file{/usr/bin/perl} by the correct path for your system. MS-DOS: A +\perl\ processor for MS-DOS such as \package{ActivePerl} can process the +\LaTeX\ auxiliary file \fnext{aux} in a command window to produce the +\authorindex\ file \fnext{ain}. + + +\section{Using the package} + +The \LaTeX\ source code includes the \ltxinp{authorindex} package +via a \ltxinp{\usepackage} statement. It may also be necessary to +replace your \ltxinp{\cite} commands by \ltxinp{\aicite} +commands\footnote{If you put the statement +\ltxinp{\let}\ltxinp{\cite}\ltxinp{=}\ltxinp{\aicite} in the +preamble after the loading of the package, \ltxinp{\cite} commands +will be equivalent to \ltxinp{\aicite} commands, and you will not +need to modify your text.}. The \ltxinp{\aicite} command behaves +like \ltxinp{\cite} but writes additional information to the +\fnext{aux} file needed to generate the author index. + +Additional commands are available. The command \ltxinp{\aimention} enters a +name into the author index that does not appear in the bibliography file +\fnext{bib}. It is not strictly a ``citation'' command because it doesn't add a +citation to the text. Its argument is an author name in the \BibTeX\ name +format like \ltxinp{\aimention\{Carl Friedrich Gau\{\string\ss\}\}}, for +example. This command is designed to bridge the gap with keyword indices and +might be useful for referring to famous people whose work (in contrast to their +publications) is common knowledge. Multiple names are possible if they are +separated by \ltxinp{and} as in the standard \BibTeX\ author format. The +command \ltxinp{\aionly} expects a bibliography key and puts the corresponding +authors in the author index without generating a citation. In a sense, it is +similar to \ltxinp{\nocite}. + +To produce the author index, run the \perl\ script \aiperl\ and \LaTeX\ +sequentially; the procedure is similar to producing the bibliography output +from \BibTeX. The command \ltxinp{\printauthorindex} marks the point where the +author index is to appear in the \LaTeX\ output. A typical sequence to run the +tools would be \LaTeX, \BibTeX, \authorindex, \LaTeX, \authorindex, \LaTeX. For +MS-DOS or Windows, the \authorindex\ step would be processed in a command +window by an explicit statement like \cmdline{perl authorindex \textit{example} + [cr]}, where \textit{example} is the name of the \fnext{aux} file and +``\cmdline{[cr]}'' indicates the enter key. In a Unix environment, the \aiperl\ +script can be invoked simply by the statement \cmdline{authorindex + \textit{example} [cr]}. + +Options to the \authorindex\ package are available,passed to the package in the +usual way \ltxinp{\usepackage[option\ldots]\{authorindex\}}. The option +\ltxinp{withbib} automatically indexes the page where a bibliography entry +appears in the references. There is also the possibility of generating an index +that is merged into the corresponding bibliography entries themselves. This +possibility is switched on by the package option \ltxinp{miniindex} discussed +more below. + +The details of including the author index are left to the author. Unlike the +commands \ltxinp{\printindex} or the \ltxinp{\thebibliography}, +\ltxinp{\printauthorindex} does not create a chapter or section heading. To +format the author index in multiple columns on a page in a one-column document, +use an additional package like \package{multicol}. With this package, a +two-column author index will be created with +\begin{verbatim} +\begin{multicols}{2} +\printauthorindex +\end{multicols} +\end{verbatim} +If you plan to generate several documents with author indices in a consistent +style, consider redefining the \ltxinp{theauthorindex} environment to fit your +needs. + + +\section{Overall structure of the index} + +\subsection{Normal \fnext{ain} file} + +The \fnext{ain} file created by the \perl\ script \aiperl\ from the \fnext{aux} +file and used by \ltxinp{\printauthorindex} will look like this: +\begin{verbatim} +\begin{theauthorindex} +\item[May, Karl] \aipages{\aifirstpage{iv}, 2, \aibibpage{77}} +\item[Musil, Robert] \aipages{7, 9, \aibibpage{\aifirstpage{77}}} +\indexspace +\item[Schmidt, Arno] \aipages{33, \aibibpage{78}} +\item[Souter, Nathaniel] \aipages{29--\aifirstpage{36}} +\end{theauthorindex} +\end{verbatim} +Note the provision for both text and bibliographical pages. Author names that +start with different letters are separated by the statement +\ltxinp{\indexspace}, which inserts a blank line between the groups. This +command has no arguments but can be redefined according to your needs inside or +outside the \ltxinp{theauthorindex} environment. Also, note the provision for a +sequential range of pages. + + +\subsection{Font sizes} + +The command \ltxinp{\aisize} controls the font size used for the author index. +It expects no arguments. You can redefine it outside the +\ltxinp{theauthorindex} environment to customize the font size. In most cases, +it will be sufficient to use one of those options in the \authorindex\ package: +\begin{description} +\item[small] will cause the author index to be typeset in small size. +\item[normal] (the default) will cause the author index to be typeset in the + normal text size. +\end{description} + + +\subsection{Separate entries for first and other authors} +\label{sec:firstandothers} + +By default, \authorindex\ generates exactly one entry for each author in the +index. All pages with citations of the author's work go into this entry, no +matter what the co-authors for the work that you cite are. + +Optionally, you can generate a reference to first authors in the author list of +all of the author's works. To this end, you call \ltxinp{\aialso} in the +preamble of your document. The command takes two string arguments. The first +argument is put before first author name, the second is used as a separator. + +Alternatively, you can change this behavior with the \ltxinp{\aisee} command. +You call \ltxinp{\aisee} in the preamble of your document with a string +argument. For authors that are not the first in the author list of a work +cited, \authorindex\ generates an entry with this authors name, followed by the +string you have given to \ltxinp{\aisee}, followed by the name of the first +author of the cited work. Entries for authors that are first (or even only) +authors of a work are listed in the author index as usual. + +For example, if you write in German, you'd put +\begin{verbatim} +\aisee{, siehe } +\end{verbatim} +in your preamble. If you write in English, you would use ``see'' instead of +``siehe''. For example, assume that we cite works with the following author +lists: ``A.~Schmidt, R.~Musil, and K.~May'' (cited on page 4); ``R.~Walser and +K.~May'' (and page 4 and 5); ``R.~Musil'' (on page 3); ``R.~Musil and +N.~Souter'' (on page 5); ``N.~Souter and R.~Musil'' (on page 2 and 6). Then, +the entries starting with ``M'' in the \fnext{ain} file look like like +\begin{verbatim} +\item[\aitop{May, K.}, siehe \aifirst{Schmidt, A.}] \aipages{4} +\item[\airep{May, K.}, siehe \aifirst{Walser, R.}] \aipages{4, 5} +\item[Musil, R.] \aipages{\aifirstpage{3}, \aifirstpage{5}} +\item[\airep{Musil, R.}, siehe \aifirst{Souter, N.}] \aipages{2, 6} +\item[\airep{Musil, R.}, siehe \aifirst{Schmidt, A.}] \aipages{4} +\end{verbatim} + + +\subsection{Mini indices} +\label{sec:mini} + +Alternatively (or additionally) to the usual author index, you can use the +package option \ltxinp{miniindex} in the preamble to cause \aiperl\ to merge a +mini index directly into your bibliography file; that is, the merge modifies +the \fnext{bbl}-file. This procedure requires that you run \aiperl\ +\emph{after} you run \bibtex. The page list is put into the single argument of +the command \ltxinp{\bibindex}. By default, \ltxinp{\bibindex} prints nothing +if its argument is empty. Otherwise, it passes the argument to +\ltxinp{\aibibindex}, which prints the pages in bold type enclosed by braces +(for example, \textbf{\{10, 11, 36\}}), as in Nelson F. Beebe's author index +package \cite{Beebe98}. For alternatives, you can redefine +\ltxinp{\aibibindex} using \ltxinp{\renewcommand}. For obvious reasons, a mini +index always contains the page numbers, even if the \ltxinp{biblabels} package +option is used. + +Normally, the mini index is placed at the end of each item. You can change +this by hacking your bibliography style file. Let it place \verb|\bibindex{}| +on its own line where you want the mini index to go, and \aiperl\ will do the +rest. + +\section{Author names} + +\subsection{Which names to include in the index?} + +There are two package options to \authorindex\ to select which type of names to +include in the index: +\begin{description} +\item[editors] will cause the editor names to be included in the author index. +\item[avoideditors] will cause the editors names to be included only if there + are no author names present for a cited work +\item[onlyauthors] (the default) will restrict the author index to the author names. +\end{description} +Previous comments concerning authors will also apply to editors when the +\ltxinp{editors} option is invoked. + +The command +\ltxinp{\aimaxauthors[}\textit{trunc\/}\verb|]{|\textit{max\/}\verb|}| limits +the maximum number of authors per work that will be included in the author +index. The optional first argument \textit{trunc\/} determines the number of +authors to be included if the maximum number is exceeded. If it is omitted, +\textit{trunc\/} is assumed equal to \textit{max}. Thus, +\ltxinp{\aimaxauthors[1]}\verb|{3}| will set the maximum number of authors to +3; for works with more than three authors only the first one will be included. +In this example, for a work by ``A. Schmidt, R. Musil, and K. May'', all of +them will appear in the author index while, for a four-author work by ``A. +Schmidt, R. Musil, K. May, and N. Souter'', only Schmidt will. This usage is +similar to the ``et al.'' commonly used in in bibliographies. With +\ltxinp{\aimaxauthors}\verb|{3}|, on the other hand, for works with more than 3 +authors, the 3 first ones will be included. For the two example author lists, +in both cases, Schmidt, Musil, and May will be listed. + +The \authorindex\ package accepts package options for only the most important +cases: +\begin{description} +\item[onlyfirst] sets the maximum number of authors (or editors) per work that + will be included in the index to 1. It corresponds to + \verb|\aimaxauthors{1}|. +\item[all] (the default) sets the maximum number of authors (or editors) per + work that will be included to 9999. It corresponds to + \verb|\aimaxauthors{9999}|. +\end{description} + + +\subsection{Formatting and sorting} + +The command \ltxinp{\ainamefmt} contains the specification for formatting and +ordering of names. Its argument is a string consisting of one or more parts +separated by semicolons. Each part is made up of one or two components, +separated by a colon. If there is only one component, the both components are +assumed to be equal. Each of the two component consists of a \BibTeX-format +string \cite{Patashnik88b}. The first component formats the way the names are +printed in the index; the second component, the way the names are sorted. It +is therefore possible to include the same name multiple times in the index, +each time sorted or printed differently. One restriction is that you cannot +have different printed representations that have the same sort format. Because +\ltxinp{\ainamefmt} can be messy to use, a few simple cases can be selected by +options to the \authorindex\ package: {\small +\begin{description} +\item[lastname] will only include the last name of the authors (and titles like + ``von'', if present). +\item[firstabbrev] will also include the abbreviated first name(s) (and + eventually also a ``jr.''), following the last name. +\item[fullname] (the default) will spell the names in full, to the extent given + in the \fnext{bib} file. +\end{description}} + +For example, the package options \ltxinp{fullname}, \ltxinp{lastname}, and +\ltxinp{firstabbrev} correspond following uses of \ltxinp{\ainamefmt}: +\begin{verbatim} +\ainamefmt{{vv }{ll}{, ff}{, jj}}} % fullname +\ainamefmt{{vv }{ll}}} % lastname +\ainamefmt{{vv }{ll}{, f.}{, jj}}} % firstabbrev +\end{verbatim} + +For a more complex example, assume we want to format the names like for the +\ltxinp{firstabbrev} option but, in addition to the normal sorting, we also +want to sort in names that have a `von'-part ignoring that part. In other +words, we want C. F. von Weizs\"{a}cker to appear both under ``V'' and ``W'' in +the index, but nonetheless always typeset as ``von Weizs\"{a}cker, C. F.'': +\begin{verbatim} +\ainamefmt{% + {vv }{ll}{, f.}{, jj};% + {vv }{ll}{, f.}{, jj}:{ll}{vv }{, f.}{, jj}% +} +\end{verbatim} +This approach would also work for name prefixes like ``van'' or ``de la''. + +Note that the command \ltxinp{\indexspace}, which separates entries that start +with a different letters, is placed according to the format used for sorting. + + +\subsection{Dealing with name variations} + +In different publications, the name of the same author may appear in different +forms. Causes of variation are differing style conventions of various +journals, inconsistencies caused by the author, or plain errors. + +Bibliographies should give the author names as close to what appears on the +publication as the bibliography style allows. This in the interest of your +readers, as is simplifies finding what you cite. But it also implies that +inconsistencies carry over to the \ltxinp{author} fields of the \BibTeX\ data +base. + +In contrast, for author indices, names should be used consistently. Readers +consult the author index to find out about the works of a particular person, +and should find all of them in a single entry, rather than scattered over +multiple entries that correspond to different forms of the same name. + +To meet the conflicting needs for bibliographies and author indices, +\authorindex\ supports two new fields for \BibTeX\ data base entries: +\begin{description} +\item[authauthor] Gives the author name list, using the authoritative form of + the authors names. The format is like for the \ltxinp{author} field. +\item[autheditor] Likewise, for editors. +\end{description} +If a new field is present in a \BibTeX\ entry, \authorindex\ uses it instead of +the \ltxinp{author} or \ltxinp{editor} field. Of course, the latter fields are +still required for \BibTeX. + + +\subsection{Fonts for the names} + +\ltxinp{\ainame} is a command with one argument. It determines how the +argument of \ltxinp{\item} inside the \ltxinp{theauthorindex} environment is +printed. + +The command \ltxinp{\aifirst} has one argument. It is used to typeset the name +of the leading author from an entry with an additional author when using the +command \ltxinp{\aisee}. The command \ltxinp{\aitop} typesets the name of the +first occurrence of an additional author, that is, an author name before the +string defined by \ltxinp{\aisee}. + +Finally, \ltxinp{\airep} typesets a name that has already been used in the +previous index entry. Look at the example in section~\ref{sec:firstandothers} +for clarification. + +By redefining these commands, you can do more than just selecting fonts. One +example would be to redefine +\begin{verbatim} +\renewcommand{\airep}[1]{---} +\end{verbatim} +to cause the name of an author to printed only once when it occurs in many +subsequent entries. + + +\subsection{Advanced customization} +\label{sec:bsthacker} + +If the standard command \ltxinp{\ainamefmt} does not provide enough +flexibility, you can use the command \ltxinp{\authorindexstyle} in the +preamble. Its single argument is the name of some \fnext{bst}-file that you +select to format the author names. + +If you decide to write a custom \fnext{bst}-file, it is necessary to understand +hacking \fnext{bst} files, e.~g.\ by reading \cite{Patashnik88b}. Your \BibTeX\ +style file needs to generate a \fnext{bbl} file that contains three lines per +author-label pair, each of which is followed by a line that contains just a +percent sign. The first line is the name formatted according to your taste, as +it appears in the index. The second line is the name format used for +sorting. The third line contains the label of the citation, or is empty. In +the latter case, the label of the previous three line entry is taken; +furthermore, this entry is assumed to refer to the same author as the current +one --- differing only in the formatting or sorting rule. The default +\fnext{bst} file used to format the names is embedded in the \perl\ script +\aiperl. You could use this as template. Use the command line option +\option{-k} for \aiperl\ (see Sec.~\ref{sec:Runai}). + +The first author of the work is expected to be dumped into the \fnext{bbl} file +first. + + +\section{Page numbers and bibliography labels} + +\subsection{Page numbers or bibliography labels?} + +You have to possibility of selecting whether you want the page numbers or the +bibliography numbers of the references to appear in the index. This selection +is done through the package options +\begin{description} +\item[biblabels] will include in the author index the reference label as it + appears in the reference list instead of the page numbers. +\item[pages] (the default) the pages of the citations. +\end{description} +With the option \ltxinp{biblabels}, every citation will be indexed. There is no +need to use the special citation commands \ltxinp{\aicite}, unless you want to +have a mini index as well (see section~\ref{sec:mini}). With this option, it +makes no sense to use either the \ltxinp{\aimention} command or the +\ltxinp{withbib} package option. + +While this manual has referred to ``pages, '' it also applies to the indexing +of bibliography labels unless explicitly noted otherwise. + + +\subsection{Ordering of pages and compression of page ranges} + +The command \ltxinp{\aipagetypeorder}\verb|{|\textit{order\/}\verb|}| can be +used to determine the relative order of different types of page numbers, such +as roman, arabic, and others. The argument \textit{order\/} is a string +consisting of a selection of the characters \ltxinp{rRnAa}, which indicate +lowercase roman, uppercase roman, arabic, uppercase alphabetic, and lowercase +alphabetic page numbers, respectively. The relative order of the letters in the +string determine the order of the page numbers. For example, the argument +\ltxinp{rn} will sort all lowercase roman pages before the arabic pages. If you +want to use lowercase alphabetic numbers, you have to use +\ltxinp{\aipagetypeorder} without putting \ltxinp{r} in the string; that is, +you can't use lowercase roman numbers and lowercase alphabetic numbers at the +same time. The same holds for using uppercase roman and alphabetical page +numbers. Composite page numbers (like ``4-17'') are split into their components +(using any character that cannot be interpreted as a digit as field separator) +and sorted with the priority of components decreasing from left to right. + +Normally, three or more adjacent page numbers are ``compressed.'' If an author +citation appears on pages 4.17, 4.18, and 4.19, the page range will appear as +``4.17--4.19'' in the index entry. However, a range of only two consecutive +pages will not be compressed. To represent such a pair by the first page number +plus some string (typically, ``f''), specify that string as the argument of +\ltxinp{\aitwosuffix} in the preamble. You can suppress range compression +altogether by using the \ltxinp{nocompress} package option. + + +\subsection{Fonts used for the pages} + +The command \ltxinp{\aipages} determines the overall font of the page numbers. +The command \ltxinp{\aibibpage} is used to switch on additional properties to +mark the pages that contain the bibliography entries of works of the author --- +relevant if the \ltxinp{withbib} package option is used. \ltxinp{\aifirstpage} +is used to print page numbers of references in which the author is the leading +author. All three commands expect one argument and can be redefined by +\ltxinp{\renewcommand}. + +\subsection{Modifying the page numbers} +\label{sec:pagerep} + +The command \ltxinp{\theaipage} determines the string representing the page +delivered to the \perl\ script \aiperl. This does not apply to bibliography +labels, even if the \ltxinp{biblabels} package option is used. By default, +this is simply defined as \ltxinp{\thepage}, but you can redefine it. +Originally, allowing \ltxinp{\theaipage} to differ from \ltxinp{\thepage} was +intended for multi-volume books, where the page numbers in each volume do not +indicate the volume number. For example, page 231 of volume II will produce +only a plain ``231'' as the page number, whereas you might prefer to have the +indication of the volume in the index such as ``II-231''. You can also do more +sophisticated things. For example, using the \package{hyperref} package with +the \ltxinp{plainpages=false} option to create hyperlinks to the page where the +citation is: +\begin{verbatim} +\def\theaipage{\string\hyperpage{\thepage}} +\end{verbatim} +NB: To avoid keep \aiperl\ from interpreting the string \ltxinp{\hyperpage} as +an alphabetic page number, you should not use alphabetic page numbering and +tell the \perl\ script about it using \ltxinp{\aipagetypeorder}. + + +\section{Running \aiperl} +\label{sec:Runai} + +Having run \LaTeX\ on the properly prepared \LaTeX\ source document, you then +use the \perl\ script \aiperl\ to process the generated \fnext{aux}-files, +which produces the author index file (extension \fnext{ain}). + +The \perl\ script can be called with any number of arguments. Without +arguments, \aiperl\ reads from the standard input. With several arguments, +\aiperl\ appends \fnext{aux} extensions wherever necessary and processes these +files. The output is written to the file whose name is extracted from the +\fnext{aux}-file for the \fnext{tex}-file where \ltxinp{\printauthorindex} was +given. It is necessary to give the \fnext{aux}-file produced by the +\fnext{tex}-file containing \verb|\begin{document}| to \aiperl; this file + passes information to the script regarding the style and content of the + index. + +If you use \ltxinp{\include} in your \LaTeX\ source document, it is +sufficient to give the master \fnext{aux}-file to \aiperl; the +\fnext{aux}-files of included files are then processed automatically. + +\aiperl\ recognizes the following command line options: +\begin{description} +\item[-d] (``draft'') Adds additional information to the \fnext{ain} file: For + each author, the labels of all references and the page numbers where they are + cited are included as comments. This detail may help if you manually edit the + generated author index. Also, some statistics are included at the bottom of + the \fnext{ain} file. This option does not work with the \option{-i} option. +\item[-h] (``help'') Prints out a + short help text. +\item[-i] (``index'') Creates a file suitable for further processing with + \mkindex\ or the like. For example, you could use that to make a common + author and subject index. Note the extension of the generated file still will + be \fnext{ain}. (Use the \option{-p} option and redirection to send the + stuff anywhere else.) +\item[-k] (``keep'') Retains the temporarily generated \fnext{bst}-file after + \aiperl\ finishes. This information will give you a good starting point for + advanced customization of the author index (see Sec.~\ref{sec:bsthacker}). +\item[-p] (``print'') Prints the result to standard output instead of writing + it to the \fnext{ain}-file. +\item[-r] (``do not recurse'') Does not automatically process \fnext{aux}-files + produced by included files. +\end{description} + + +\section{\authorindex\ and other packages} + +\subsection{Compatible packages} + +\subsubsection{Standard distribution package} + +The standard \package{cite} package included with the \LaTeX\ distribution +seems to work with \authorindex\ without problems. + +\subsubsection{chapterbib} + +The \package{chapterbib} package also works well with \authorindex. If you +want to use the mini indices, be sure to run \aiperl\ separately on the main +\fnext{aux}-file plus the \fnext{aux}-file for each chapter using the +\option{-r} option (see section~\ref{sec:Runai}). In addition, you may want to +run \aiperl\ on the main \fnext{aux}-file to generate an author index for all +chapters. For example, you might use a sequence of the form: +\begin{verbatim} + authorindex -r main chapter1 + authorindex -r main chapter2 + authorindex main +\end{verbatim} +If you require chapterwise author indices, after the first two \authorindex\ +runs in the above example, you should rename \file{main.ain} to something else +and \ltxinp{\input} these files in the place where you want the chapterwise +authorindex to appear. + +\subsubsection{hyperref} + +The script \authorindex\ works well with \package{hyperref}. In the standard +version, the pages in the author index are not linked back to the page with the +citation. Section~\ref{sec:pagerep} describes how to fix this problem. + +\subsection{Less compatible packages} + +Most problems with other bibliographical packages arise because the packages +override or skip certain citation functions. The \authorindex\ package modifies +these functions to write page information along with the citation key to the +\fnext{aux} file. In the following examples, we show how to re-establish this +additional output for a few specific packages. Please note that these ``fixes'' +may no longer work if newer versions of these packages appear. + +If you use a non-compatible package that is not listed below, it is worthwile +to have a look into its source code. In the simplest case, the package might +include one of the listed packages (using \ltxinp{\usepackage}), and hence one +of the examples below applies. Others might require more effort, but the basic +strategy for a fix will be always similar to the examples below. If you +encounter non-compatible packages, please notify me about them (ideally, with +instructions for a fix) so that I can include them in this manual. + + +\subsubsection{\package{chicago}} +\label{sec:chicago} + +The standard version of the \package{chicago} package does not work with +\authorindex. For this package, there is a patch that apparently makes it work +with \authorindex. In the file \file{chicago.sty}, you replace the lines +\begin{verbatim} +\def\@citex[#1]#2{% +\end{verbatim} +with +\begin{verbatim} +\def\@citex[#1]#2{\@aicitey{#2}% +\end{verbatim} +and +\begin{verbatim} +\def\@citedatax[#1]#2{% +\end{verbatim} +with +\begin{verbatim} +\def\@citedatax[#1]#2{\@aicitey{#2}% +\end{verbatim} +and save the modified file under a new name, e.~g.\ \file{aichicago.sty}. Use +this file in place of the file \file{chicago.sty}. + + +\subsubsection{\package{harvard}} + +The \package{harvard} package can be made to work with \authorindex by adding +code to the document preamble. After loading the \package{harvard} package +with \ltxinp{\usepackage}, write the following lines into the preamble of your +\LaTeX-source file: +\begin{verbatim} +\makeatletter +\renewcommand{\HAR@citetoaux}[1]{% + \if@filesw\immediate\write\@auxout{\string\citation{#1}}\fi% + \if@filesw\@for\@citeb:=#1\do{\immediate\write\@auxout{% + \string\citationpage{\@citeb}{\thepage}}}\fi}% +\makeatother +\end{verbatim} +Then, in the main text, use the \package{harvard} citation commands +\ltxinp{\cite}, \ltxinp{\citeyear}, etc., exactly as you would normally do +without the \authorindex\ package. + + +\subsubsection{\package{natbib}} + +Like \package{chicago}, the package \package{natbib} also conflicts with +\authorindex. The following fix is based on a similar fix by Michael Friendly +and Patrick W.\ Daly for Nelson Beebe's \package{authidx} package +\cite{Beebe98}, plus additional support for \package{natbib}'s numerical mode +as proposed by Pieter Eendebak. You insert in your \file{natbib.cfg} the +following lines: +\begin{verbatim} +% natbib.cfg +\AtBeginDocument{% +\@ifpackageloaded{authorindex}{% + \ifNAT@numbers + \let\org@@citex\NAT@citexnum + \else + \let\org@@citex\NAT@citex + \fi + \def\@citex[#1][#2]#3{% + \typeout{indexing: [#1][#2]{#3}}% + \org@@citex[#1][#2]{#3}% + \@aicitey{#3}}% + \renewcommand\NAT@wrout[5]{% + \if@filesw{% + \let\protect\noexpand\let~\relax + \immediate\write\@auxout{\string\aibibcite{#5}{#1}}% + \immediate\write\@auxout{\string\bibcite{#5}{{#1}{#2}{{#3}}{{#4}}}}}% + \fi}}{}} +\endinput +\end{verbatim} +Please note that I tested this work-around superficially. It does not repair a +conflict that occurs when the \authorindex\ package option \ltxinp{withbib} is +used. + +\subsubsection{\package{bibunits}} + +To make \package{bibunits} to work with \authorindex, in \file{bibunits.sty}, +replace the lines +\begin{verbatim} +\def\bu@@citex[#1]#2{% +\end{verbatim} +by +\begin{verbatim} +\def\bu@@citex[#1]#2{\@aicitey{#2}% +\end{verbatim} +and save the modfied file under a new name. + + +\subsubsection{Other packages} + +\begin{description} +\item[\package{monog3}] A class from Oxford University Press that used + \package{chicago}. See section~\ref{sec:chicago}. +\end{description} + + +\section{Problems and restrictions} + +Currently, I am aware of the following problems and restrictions: +\begin{itemize} +\item Compression of page numbers ignores whether the pages will be printed in + the same font; that is, you might get something like ``7--\textbf{9}''. +\item Compression always uses the full page numbers, that is you will always + get something like ``4.8--4.10'' rather than ``4.8--10''. +\item Sorting of names is restricted. At this time, special characters are + stripped, the case is ignored, and a normal comparison according to the + ASCII~Code is done. This might not be what you want if you have accented + characters. Consider using the option \option{-i} in conjunction with + additional processing by a more flexible tool. +\item If you use \ltxinp{\aicite} with multiple arguments and a page break + occurs within the list of generated references, one part of the citations + will be associated with the wrong page. +\item You can not use the package when you explicitly type your bibliography in + your \LaTeX\ file (\ltxinp{\bibitem}) instead of using \BibTeX. Consider + using \BibTeX\ instead. It is a powerful bibliographical tool worth the + small additional effort. +\end{itemize} + +\section{Acknowledgement} + +I want to thank Mark A. Gordon for his substantial improvements to the language +and presentation in this manual. + + +\begin{thebibliography}{3} + +\bibitem{Patashnik88a} +O.~Patashnik. +\newblock \textit{{\BibTeX ing}} (1988). +\newblock Documentation for general {\BibTeX} users. + +\bibitem{Beebe98} +N.~H.~F. Beebe. +\newblock \textit{{AUTHIDX}: An author/editor indexing package}. +\newblock TUGboat \textbf{19}(1):1001--1007 (1998). + +\bibitem{Patashnik88b} +O.~Patashnik. +\newblock \textit{Designing {\BibTeX} styles} (1988). +\newblock The part of \BibTeX's documentation that's not meant for general + users. + +\end{thebibliography} + +\end{document} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: |