diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/bibhtml')
| -rw-r--r-- | Master/texmf-dist/doc/latex/bibhtml/LICENCE | 340 | ||||
| -rwxr-xr-x | Master/texmf-dist/doc/latex/bibhtml/bibhtml | 464 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/bibhtml/bibhtml.html | 479 |
3 files changed, 1283 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/bibhtml/LICENCE b/Master/texmf-dist/doc/latex/bibhtml/LICENCE new file mode 100644 index 00000000000..3912109b5cd --- /dev/null +++ b/Master/texmf-dist/doc/latex/bibhtml/LICENCE @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/Master/texmf-dist/doc/latex/bibhtml/bibhtml b/Master/texmf-dist/doc/latex/bibhtml/bibhtml new file mode 100755 index 00000000000..4a1c9104be8 --- /dev/null +++ b/Master/texmf-dist/doc/latex/bibhtml/bibhtml @@ -0,0 +1,464 @@ +#! /usr/bin/env perl +## 'perl -w' is good, but the PERL on the previous line is substituted, +## by default, by '/usr/bin/env perl', and that doesn't always cope well +## with multiple arguments, so leave the option off. +# +# This software is copyright, 1999, 2005, Norman Gray. +# +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +# +# Author: Norman Gray, norman@astro.gla.ac.uk. +# Department of Physics and Astronomy, University of Glasgow, UK +# +# See the file LICENCE for a copy of the GPL. +# You can also find an online copy at http://www.gnu.org/copyleft/gpl.html . +# +# $Id: bibhtml.in,v 1.5 2005/09/19 16:18:43 norman Exp $ +# +# See <http://www.astro.gla.ac.uk/users/norman/distrib/bibhtml.html> +# for documentation. + +use strict; + +my $version = 'Bibhtml, version 1.2, Norman Gray <norman@astro.gla.ac.uk>, 2005 September 19'; + + +# configuration... +my $rootname = 'bibliography'; +my $bibdata = ''; # default bibdata is ./bib.bib +my $bibstyle = ''; # default, below, is plainhtml +my $bibconfig = 'bibhtml.config'; # configuration file + +my $html3 = 0; +my $citeall = 0; +my $verbose = 1; +my $mergebib = 0; +my $strippis = 0; # if true, then strip PIs from output + +# configuration variables +my $endash; +my $nbsp; + +my $bibfilename; # the name of the .bib file +my $bblfilename; # the name of the generated .bbl file +my $auxfilename; # the .aux file we generate here + +# control flags +my $phase; +my $foundslot; # true when we're in the gap between + # <?bibhtml start...end?> + +# set to 1 to switch on debugging, set > 1 to exit after option parsing +my $debug = 0; + +# normalise progname - part after last slash +$0 =~ /([^\/]*)$/; +my $progname = $1; + +if ($#ARGV < $[) { + print "Usage: $progname filename ...\n[$version]\n"; + exit 1; +} + +# get directory of first arg (this is where we'll search for bibhtml.config) +$ARGV[0] =~ /[^\/:]*$/; +my $defdir = $`; +#print "defdir $defdir\n"; + + +#------ + +# if -c is present in the argument list, then undefine $bibconfig, +# and so don't read it automatically at the beginning +for (@ARGV) { if (/^-c/) { undef ($bibconfig); last; }} +if (defined ($bibconfig) && (-r $bibconfig)) { + readconfig ($bibconfig); +} + +# Option processing +while ($_ = $ARGV[0], /^[-+]/) +{ + # print "ARGV[0]=$_\n"; + if (/^([-+])3/ ) { $html3= ($1 eq '+') } + if (/^-v/) { $verbose = 1 } + if (/^-q/) { $verbose = 0 } + if (/^-a/) { $citeall = 1 } + if (/^-V/) { print STDERR $version, "\n"; exit } + if (/^--version/) { print STDERR $version, "\n"; exit } + if (/^--merge/) { $mergebib = 1 } + if (/^--strip/) { $strippis = 1 } + if (/^--help/) { printhelp(); exit } + + shift; + last if ($#ARGV < $[); + if (/^-r/) { $rootname = $ARGV[0]; shift } + if (/^-b/) { $bibdata = $ARGV[0]; shift } + if (/^-s/) { $bibstyle = $ARGV[0]; shift } + if (/^-c/) { my $bibconfig = $ARGV[0]; + shift; + readconfig ($bibconfig); } + last if ($#ARGV < $[); +} + + +if ($debug) +{ + # debugging arglist... + print STDERR "rootname $rootname, bibdata $bibdata\n"; + if ($html3) { print STDERR "html3\n"; } + if ($verbose) { print STDERR "verbose\n"; } + if ($citeall) { print STDERR "citeall\n"; } + print STDERR "ARGV @ARGV\n"; + exit if ($debug > 1); +} + +if ($mergebib) { + # usage is bibhtml file.bbl file.html - do nothing other than + # merge a bbl file into an html file + if ($#ARGV < 1) { + print "Usage: $progname --merge file.bbl file.html\n"; + exit; + } + + $phase = +1; + $bblfilename = $ARGV[0]; + $bibfilename = $ARGV[1]; + # Insist that both files have the correct extension + # This route will mostly be called by scripts, so this check is + # both useful and easily satisfied + ($bblfilename =~ /\.bbl$/) && ($bibfilename =~ /\.html$/) + || do { + print STDERR "Usage: $progname --merge file.bbl file.html\n\tfile extensions required!\n"; + exit; + }; +} +else +{ + if ($#ARGV < $[) + { + print "Usage: $progname filename ...\n"; + exit; + } + + # If the command name is bibhtml, then do everything. + # If it isn't, then use the name of the (first) argument to work out which + # phase to perform. If it's a .bbl file, then merge it with the .html + # file, if not, then create the .aux file ready for BibTeX to be + # invoked manually. + if ($progname eq 'bibhtml') + { + $phase = 0; + } + else + { + if ($ARGV[0] =~ /(.*)\.bbl$/) + { + $rootname = $1; + $phase = +1; + } + else + { + $phase = -1; + } + } +} + +if ($debug) +{ + print STDERR "rootname $rootname\nbibdata $bibdata\nphase $phase, html3 $html3\n"; +#exit; +} + + +my @date = localtime(time); +my @mname = ("January", "February", "March", "April", "May", "June", + "July", "August", "September", "October", "November", "December"); + +$bblfilename = "$rootname.bbl" unless (defined ($bblfilename)); +$bibfilename = "$rootname.html" unless (defined ($bibfilename)); +$auxfilename = "$rootname.aux" unless (defined ($auxfilename)); + +print "bibfilename=$bibfilename\nbibdata=$bibdata\n" if $verbose; + +######################################## +# +# Start the scanning phase + +if ($phase <= 0) # -1 or 0 +{ + print "Creating $auxfilename...\n" if ($verbose); + + open (OUT, ">$auxfilename") || die "can't open $auxfilename to write\n"; + print OUT "\\relax\n"; # not really necessary, but... + + if ($citeall) + { + print "Citing all...\n" if ($verbose); + print OUT "\\citation{*}\n"; + } + else + { + foreach my $fn (@ARGV) + { + my $t; # temporary string + print "scanning $fn...\n" if ($verbose); + + open (IN, "$fn") || die "can't open $fn to read\n"; + + while (<IN>) + { + # Match possibly multiple times on one line + # Note bibfilename must be present, even if this is the + # bibliography itself. + foreach my $m (/$bibfilename#([^\"]+)/g) { + print OUT "\\citation{$m}\n"; + } + if (($t) = /<\?bibhtml\s+bibdata\s+([\w,]*)/) { + # accumulate bibdata + if ($bibdata eq '') { + $bibdata = $t; + } else { + $bibdata .= ',' . $t; + } + print "bibdata=$bibdata\n" if $verbose; + } + if (($t) = /<\?bibhtml\s+bibstyle\s+(\w*)/) { + # do not override any value specified on the command line + $bibstyle = $t if $bibstyle eq ''; + print "bibstyle=$bibstyle\n" if $verbose; + } + } + + close (IN); + } + } + + $bibdata = 'bib' if ($bibdata eq ''); + $bibstyle = 'plainhtml' if ($bibstyle eq ''); + + print OUT "\\bibstyle{$bibstyle}\n"; + print OUT "\\bibdata{$bibdata}\n"; + + close (OUT); +} + +######################################## +# +# Call BibTeX + +if ($phase == 0) +{ + print "Calling BibTeX...\n" if ($verbose); + + system ("bibtex $rootname")==0 || die "can't bibtex $auxfilename\n"; +} + +######################################## +# +# Substitution phase + +if ($phase >= 0 && -r "$bblfilename") # $phase +1 or 0 +{ + print "Merging $bblfilename into $bibfilename...\n" if ($verbose); + + # now merge the new bbl file with the old bibfilename, between the + # pattern /<?\s*bibhtml start/ and 'end' + + + if ($debug) + { + open (ORIG, "$bibfilename")||die "can't open $bibfilename to read"; + } + else + { + rename ($bibfilename, "$bibfilename.old")||die "can't rename $bibfilename"; + open (OUT, ">$bibfilename") ||die "can't open $bibfilename to write"; + select (OUT); + open (ORIG, "$bibfilename.old")||die "can't open $bibfilename.old to read"; + } + open (BBL, "$bblfilename") ||die "can't open $bblfilename to read"; + + + $foundslot = 0; # copy the old to the new up to pattern + + FINDSLOT: while (<ORIG>) + { + if (/<\?bibhtml\s+today/ || /<!--\s*bibhtml:today/) + { + print unless $strippis; + # gobble a line containing the old date + <ORIG>; + print "$date[3] $mname[$date[4]] 19$date[5]\n"; + } + elsif (/<\?bibhtml\s+start/ || /<!--\s*bibhtml:start/) + { + print unless $strippis; + $foundslot = 1; + print STDERR "Found start\n" if $debug; + last FINDSLOT; + } + elsif (/<\?bibhtml\s+insert/) + { + # don't print this line + $foundslot = 2; + print STDERR "Found insertion point\n" if $debug; + last FINDSLOT; + } else { + if ($strippis) + { + print unless /<\?bibhtml/; + } else { + print; + } + } + } + + $foundslot || die "couldn't find the insertion point"; + + if ($html3) + { + $nbsp=' '; + $endash='&endash;'; + } + else + { + $nbsp=' '; + $endash='-'; + } + + while (<BBL>) + { + # If a line ends with a %, then remove the %\n. write$ does + # a decent job of line breaking, but if it can't break a line + # at space, it puts in a %, which is OK in TeX, but messes + # up HTML. + if (/%$/) { + chop; chop; + $_ .= <BBL>; + } + + # Spot hrefs in the current line: if we find any, emit them and + # remove them from $_, so they're escaped as appropriate for URLs, + # which is different from the escaping required for text, below. + # We lose in principle, if there are any characters which need + # escaped before the href, but the output of bibtex is pretty + # consistent, and doesn't produce these in fact. + my $href; + if (($href) = /(.*href[^>]*)/) { + $href =~ s/\&/\&/g; + $href =~ s/\~/%7e/g; + print "$href\n"; + s{.*href[^>]*}{}; + } + s/\&/\&/g; + s/\~/$nbsp/g ; + s/[\{\}]//g ; + s/--/$endash/g ; + print; + } + + if ($foundslot > 1) + { + # we found <?bibhtml insert?> -- there is no end marker to be found + $foundslot = 0; + } else { + # we found <?bibhtml start?> -- look for the end marker + $foundslot = 0; + + # now discard lines of the input file until we find one which + # matches <?bibhtml end?> + SKIPGAP: while (<ORIG>) + { + if (/<\?bibhtml\s+end/ || /--\s*bibhtml:end/) + { + print unless $strippis; + $foundslot = 1; + print STDERR "Found end\n" if $debug; + last SKIPGAP; + } + } + + $foundslot || warn "couldn't find end marker"; + } + + # now copy the remainder of the file to OUT + while (<ORIG>) + { + if (/<\?bibhtml\s+today/ || /--\s*bibhtml:today/) + { + print unless $strippis; + # gobble a line + <ORIG>; + print "$date[3] $mname[$date[4]] 19$date[5]\n"; + } else { + if ($strippis) + { + print unless /<\?bibhtml/; + } else { + print; + } + } + } + + close (ORIG); + close (BBL); + close (OUT) if (!$debug); +} + + +sub readconfig { + my $bibconfig = shift; + if (-r $bibconfig) + { + print STDERR "reading config $bibconfig\n"; + open (CONF, $bibconfig); + $_ = <CONF>; + chop; + my @newargs = split (/ +/); + close (CONF); + unshift (@ARGV, @newargs); + print STDERR "readconfig: ARGV[0]=($ARGV[0]), ARGV=@ARGV\n" if ($debug); + } + else + { + print STDERR "no config file $bibconfig\n"; + } +} + +sub printhelp { + print STDOUT <<\_EOD; +This is bibhtml version 1.2, 2005 September 19. + +Usage: + % bibhtml [options...] filename... + % bibhtml --merge file.bbl file.html + +Options: + -3 Opposite of +3 -- do not use these entities + +3 Use HTML3 entities (ie,   and &enspace) as appropriate + -a Produce citations for the entire BibTeX database + (as if \nocite{*} had been included in a LaTeX file) + -b bibdata Specify the name of the BibTeX database file. + -c configfile Specify a configuration file + --merge Merge mode: merge a bbl file into an html file + --help Print this help and exit + -q Be quiet -- opposite of -v + -r rootname Set the root file name: default is 'bibliography' + -s bibstyle Name of the bibliography style file. + --strip Strip the processing instructions out of the file + -v Be verbose (default) + -V, --version Show the version number and exit +_EOD +} diff --git a/Master/texmf-dist/doc/latex/bibhtml/bibhtml.html b/Master/texmf-dist/doc/latex/bibhtml/bibhtml.html new file mode 100644 index 00000000000..5d3286e4a58 --- /dev/null +++ b/Master/texmf-dist/doc/latex/bibhtml/bibhtml.html @@ -0,0 +1,479 @@ +<?xml version="1.0"?> <!-- -*- xml -*- --> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "xhtml1/xhtml1-strict.dtd" + > + +<!-- $Id: bibhtml.html.in,v 1.7 2005/09/19 16:08:41 norman Exp $ --> + +<html> + <head> + <title>Bibhtml documentation</title> + <meta name="keywords" content="bibhtml, bibtex, HTML"/> + <link href="http://www.astro.gla.ac.uk/users/norman/" rev="author"/> + <link type="text/css" rel="stylesheet" + href="http://www.astro.gla.ac.uk/users/norman/style.css"/> + </head> + +<body> + +<h1>Bibhtml</h1> + +<div class='abstract'> +<p><em>Bibhtml</em> consists of a Perl script and a BibTeX style +file, which together allow you to compile a bibliography for a +collection of HTML files. The references in the text are linked +directly to the corresponding bibliography entry, and if a URL is +defined in the entry within the BibTeX database file, then the +generated bibliography entry is linked to this.</p> + +<p>This page is <code>http://purl.org/nxg/dist/bibhtml</code></p> + +<p>This documentation describes +<em>bibhtml, version 1.2, 2005 September 19</em>.</p> +</div> + +<h3>Contents</h3> +<ul> +<li><a href='#usage'>Usage</a> +<ul> +<li>The BibTeX database</li> +<li>Preparing the text</li> +<li><a href='#pis' >Preparing the bibliography file -- processing +instructions supported</a></li> +<li><a href='#bst-files'>BibTeX style files</a></li> +</ul></li> +<li><a href='#running'>Running <em>bibhtml</em> -- options</a></li> +<li><a href='#install'>Installation</a></li> +<li><a href='#two-pass'>Two-pass bibhtml</a></li> +<li><a href='#example'>Example</a></li> +<li><a href='#refs'>References</a></li> +<li><a href='#dist'>Distribution</a> + <ul> + <li><a href='#changes'>Changes</a></li> + <li><a href='#get'>Obtaining <em>bibhtml</em></a></li> + <li><a href='#licence'>Licence</a></li> + </ul> +</li> +</ul> + + + +<p><em>Bibhtml</em> consists of a Perl script and a number of BibTeX style +files, which together allow you to compile a bibliography for a +collection of HTML files. The references in the text are linked +directly to the corresponding bibliography entry, and if a URL is +defined in the entry within the BibTeX database file, then the +generated bibliography entry is linked to this.</p> + +<p>The BibTeX style files are <code>plainhtml.bst</code> and +<code>alphahtml.bst</code>, which are derived from the standard files +<code>plain.bst</code> and <code>alpha.bst</code>. As well, there are +<code>.bst</code> files which produce their output in date order (see +<a href="#bst-files" >below</a>). You can specify these to +<em>bibhtml</em> using either the <a href="#opt-s"><code>-s</code> +option</a> or the processing instructions described <a href="#pis" +>below</a>.</p> + +<p>The BibTeX style files distributed as part of this package are also +of considerable use in isolation.</p> + +<h2><a name='usage'>Usage</a></h2> + +<h3>The BibTeX database</h3> + +<p><em>Bibhtml</em> works with a standard BibTeX database -- it is +intended to be compatible with a database used in the standard way +with LaTeX. The <a href="#bst-files" >BibTeX style files</a> +distributed with this package define an additional +<code>url</code> field: if this is present, then the generated entry +will contain a link to this URL. They also define an +<code>eprint</code> field -- if you do not use the LANL preprint +archive, this will be of no interest to you.</p> + +<p>TeX features such as <code>~</code> and <code>--</code> are translated to +corresponding HTML entities (controlled with the <code>+3</code> +switch, see below), but other TeX constructions will make their way +into the generated HTML, and look a little odd. I might try to deal +with these in future versions. </p> + +<h3>Preparing the text</h3> + +<p>You prepare your text simply by including links to the bibliography file +(the default is <code>bibliography.html</code>), followed by a fragment +composed of the BibTeX citation key. Thus, you might cite [grendel89] +with</p> +<pre><a href="bibliography.html#grendel89">(Grendel, 1989)</a></pre> +<p>(of course, the link text can be anything you like). That's all there is to +it. When you run <em>bibhtml</em>, it generates an +<code>.aux</code> file which makes BibTeX produce references for exactly those +keys which appear in this way. </p> + +<h3><a name="pis" >Preparing the bibliography file -- processing +instructions supported</a></h3> + +<p>The bibliography file is an ordinary HTML document (which may +itself have citations within it), distinguished only by having two +processing instructions within it. +<em>Bibhtml</em> replaces everything between +<code><?bibhtml start ?></code> +and +<code><?bibhtml end ?></code> +(which should be on lines by themselves) with the formatted +bibliography. It leaves those instructions in place, naturally, so once +this file is set up, you shouldn't have to touch it again. Older +versions of bibhtml used the magic comments <code><-- bibhtml start +--></code> and <code><-- bibhtml end --></code>: these are +still supported, but are deprecated and may disappear in a future version.</p> + +<p>Alternatively, you may include the processing instruction +<code><?bibhtml insert?></code>. This acts broadly like the +<code>start</code> and <code>end</code> processing instructions, +except that the line is completely replaced by the inserted +bibliography. This is useful if the file being processed is a +generated file (perhaps the output of a separate XML tool-chain, for +example), which will not therefore have to be rescanned in future.</p> + +<p>You can specify the bibliography database and style file either on +the command line (see <a href="#running" >below</a>) or using the +<code><?bibhtml bibdata </code><em>bibfile</em><code>?></code> +and <code><?bibhtml bibstyle</code><em>stylefile</em><code>?></code> instructions. The +value of `bibdata' is cumulative, and appends to any value specified +on the command line. A value of `bibstyle' specified on the command +line, in contrast, overrides any value in the file.</p> + +<p>As a special case, <em>bibhtml</em> also replaces the line <em>after</em> a +comment <code><?bibhtml today ?></code> with today's date.</p> + +<p>Summary of processing instructions:</p> + +<dl> +<dt><code><?bibhtml start?></code> and <code><?bibhtml +stop?></code></dt> +<dd>Bracket the bibliography -- any text between these PIs is replaced +when <em>bibhtml</em> is next run.</dd> + +<dt><code><?bibhtml insert?></code></dt> +<dd>This PI is replaced by the bibliography when <em>bibhtml</em> is +next run. This PI is always removed, irrespective of the presence or +absence of the <code>--strip</code> option.</dd> + +<dt><code><?bibhtml bibdata </code><em>bibfile</em><code>?></code></dt> +<dd>Specify the bibliography database to be used. This is the +analogue of a +<code>\bibliography{</code><em>bibfile</em><code>}</code> command in a +LaTeX file; see also the <code>-b</code> command-line option.</dd> + +<dt><code><?bibhtml bibstyle </code><em>stylefile</em><code>?></code></dt> +<dd>Specify the bibliography style to be used. This is the analogue +of <code>\bibliographystyle{</code><em>stylefile</em><code>}</code> +command in a LaTex file; see also the <code>-s</code> command-line option.</dd> + +<dt><code><?bibhtml today?></code></dt> +<dd>Replace the <em>following</em> line by today's date.</dd> +</dl> + +<h3><a name='bst-files'>BibTeX style files</a></h3> + +<p><em>bibhtml</em> depends on several BibTeX style files. +<code>plainhtml.bst</code>, <code>plainhtmldate.bst</code> and +<code>plainhtmldater.bst</code> are derived from the standard +<code>plain.bst</code>. All produce HTML, but the latter two sort the +output by date and reverse date, rather than by author. +<code>alphahtml.bst</code> and friends were derived from the standard +<code>alpha.bst</code>, and contributed to the package, by Franz +G. Fischer, <code>Franz.Fischer@lpr.e-technik.tu-muenchen.de</code>, +to whom thanks are due.</p> + +<p>These style files support an additional entry type, +<code>@webpage</code>, and two additional fields on all entry types, +<code>url</code> and <code>lastchecked</code>, which give the URL +associated with the reference, and the date at which the URL was last +verified to be still present. See also the <a +href="http://purl.org/nxg/dist/urlbst" ><code>urlbst</code> +package</a>, which performs a different role, but implements the same +BibTeX extensions.</p> + +<p>Although these style files are distributed as part of +<em>bibhtml</em> they are also useful in isolation, as part of a +larger system which generates HTML.</p> + +<h2><a name='running'>Running <em>bibhtml</em> -- options</a></h2> + +<p><em>Usage</em></p> +<pre> +% bibhtml [options...] filename... +% bibhtml --merge file.bbl file.html +</pre> + +<p>The <code>filename</code> argument is the name of a file to be scanned.</p> + +<p><em>Bibhtml</em> takes a list of HTML files as argument (though see +<a href="#two-pass">below</a> for a two-pass variant). It creates an +<code>.aux</code> file, runs BibTeX, and merges the resulting +<code>.bbl</code> file (if it exists) into <code>bibliography.html</code>, or +whatever has been specified as the bibliography file name. </p> + +<p>There are several options:</p> +<dl> +<dt>-3, +3</dt> +<dd>Set this to +3 if you want <code>~</code> translated to +<code>&nbsp;</code>, and <code>--</code> to +<code>&enspace;</code>. Or set it to -3 (the default) if you +don't.</dd> + +<dt>-a</dt> +<dd>If this option is set, <em>bibhtml</em> won't bother scanning any +files at all, and will generate references for all the entries in your +database. This is equivalent to <code>\nocite{*}</code> in LaTeX.</dd> + +<dt>-b bibdata</dt> +<dd>The name of your BibTeX database file, as it would be specified in a +<code>\bibliography{}</code> command in LaTeX. Unless <em>you</em> happen to +keep all your references in a file called <code>bib.bib</code>, you'll +probably want to change this. Or you can use the <code><?bibhtml +bibdata xxx?></code> <a href="#pis" >processing instruction</a>.</dd> + +<dt>-c configfile</dt> +<dd>Specifies a configuration file which contains a single line of +options, which are inserted in the command line at that point.</dd> + +<dt><a name='merge'>--merge</a></dt> +<dd>In this special case, <em>bibhtml</em> takes two arguments, a +<code>.bbl</code> file and an <code>.html</code> file, +merges the first into the second, and nothing else. It's +intended to be used when you have generated a +<code>.bbl</code> file by a separate run of BibTeX, and simply +wish to merge the results into your bibliography file. As +such, it will most likely be useful as part of a script, or +other post-processing system.</dd> + +<dt>-r rootname</dt> +<dd>Specify this and you'll create <code>rootname.html</code>, +<code>rootname.aux</code> and so on. Why not just stick with the default +`bibliography'...? </dd> + +<dt><a name='opt-s'>-s bibstyle</a></dt> +<dd>The name of the BibTeX bibliography style you want to use, as it +would be specified for the <code>\bibstyle</code> command in +LaTeX. If you want to have a different layout for your HTML +bibliographies, please don't change the file plainhtml.bst +distributed with bibhtml. Instead, make a <em>copy</em> of +plainhtml.bst under a different name, edit it as much as you +like, and use this option of bibhtml to use the modified +version instead of the default. Or you can use the <code><?bibhtml +bibstyle xxx?></code> <a href='#pis' >processing instruction</a>.</dd> + +<dt><a name='strip'>--strip</a></dt> +<dd>If this option is set, then strip all processing-instruction lines +from the output file. This means that the resulting file cannot be +processed again by <em>bibhtml</em>, and so is appropriate when the +file is the output of a separate tool-chain.</dd> + +<dt>-V, --version</dt> +<dd>Bibhtml prints the version information and exits.</dd> + +<dt>-v, -q</dt> +<dd>Do you want the program to be verbose or quiet? The default is -v, +verbose.</dd> + +</dl> + +<p>The defaults for the various parameters are unlikely to be helpful, +so you're likely to want to set one or more of them every time you run +the program. It is for this reason, and because you're likely to want +the same set of options every time you create the bibliography for a +set of files in a directory, that you can put a collection of options +in a configuration file. This can be specified on the command line +with the option <code>-c configfilename</code>. If this option +is not given, then <em>bibhtml</em> looks for a file named +<code>bibhtml.config</code>. For example, the configuration +file might contain:</p> + +<pre> +-b mybib +3 -r refs +</pre> + +<h2><a name='install'>Installation</a></h2> + +<p>Nothing to it.... On Unix, for example, put <em>bibhtml</em> +somewhere in your path and make it executable (<code>chmod u+x +bibhtml</code>), and put <code>*.bst</code> somewhere BibTeX +will find it (this means either looking at the +environment variable <code>BSTINPUTS</code>, or running the command +<kbd>kpsepath bst</kbd>, if you have it). If you want to use the <a +href="#two-pass">two-pass variant</a> of the program, then make a symbolic +link with <code>ln -s bibhtml bibhtml2</code>.</p> + +<p>If you wish, you may change the distributed BibTeX style files (see +<a href="#bst-files" >above</a>) to the extent of changing the +`eprint' mirror site from the master <code>xxx.lanl.gov</code> to a +more local mirror. If you don't use the LANL preprint archive, this +will be of no interest to you.</p> + +<h2><a name='two-pass'>Two-pass bibhtml</a></h2> + +<p>You might sometimes have a need to invoke the +two phases separately. If you make a symbolic link to the program via +<code>ln -s bibhtml bibhtml2</code>, then you can generate an +aux-file alone by giving the command <code>bibhtml2 *.html</code>, +say; and you can merge a bbl-file into the bibliography file with the +command <code>bibhtml2 bibliography.bbl</code>. The command line option +<code>--merge</code> <a href="#merge">above</a> may be more suitable +if you are calling this code from a script, as it requires you to +specify both the <code>.bbl</code> and the <code>.html</code> file it +is being merged with, (and so it is more robust, and more flexible).</p> + +<p>On Unix, this works because the program is able to +detect the name it was invoked under. This may be more difficult on other +platforms. If so, please get in touch, with suggestions. </p> + + +<h2><a name='example'>Example</a></h2> + +<p>There are multiple sources of advice for how to cite electronic +documents. The most formal are an ISO standard <a +href="bibhtml.html#iso690">[ISO 690-2]</a>, and the American +Psychological Association's guidance (<a href="bibhtml.html#apa03" +>[APA 2003]</a>. As well, there are older, but still useful +discussions in +<a href="bibhtml.html#walker95">Walker</a> and +<a href="bibhtml.html#emory95">Emory</a>.</p> + +<p>We also include here a <a href="bibhtml.html#test" >test</a> entry, +which has some odd characters in the title and URL.</p> + +<p>This file was processed with the command <code>bibhtml -r bibhtml +bibhtml.html</code> to produce the document you are reading now.</p> + +<h2><a name='refs'>References</a></h2> + +<?bibhtml start?> +<dl> + +<dt><a name="apa03">[apa03] American Psychological Society.</a></dt> <dd> + <a href="http://www.apastyle.org/elecref.html" +>APA style: Electronic + references</a>. + [Online, cited September 2005]. +</dd> + +<dt><a name="test">[test] A. N. Experimenter.</a></dt> <dd> + <a + href="http://www.example.org/%7etilde/query?arg1=%1e&arg2=one;two&moreargswhichmaketheurlquitelong" +>bibhtml tests - how do we handle odd ( &) + characters?</a>. + This is a test entry. +</dd> + +<dt><a name="iso690">[iso690] ISO 690-2.</a></dt> <dd> + <a href="http://www.collectionscanada.ca/iso/tc46sc9/standard/690-2e.htm" + + >ISO 690-2, bibliographic references to electronic documents + (excerpts)</a>. + [Online, cited September 2005]. +</dd> + +<dt><a name="emory95">[emory95] libsf@web.cc.emory.edu.</a></dt> <dd> + <a href="http://www.cc.emory.edu/WHSCL/citation.formats.html" +>Citation + formats</a>. + [Online]. +</dd> + +<dt><a name="walker95">[walker95] Janice R Walker.</a></dt> <dd> + <a href="http://www.columbia.edu/cu/cup/cgos/idx_basic.html" +>MLA-style + citations of electronic sources</a>. + Technical Report 4/95, Department of English, University of South Florida, + January 1995. + Endorsed by the Alliance for Computers and Writing. +</dd> + +</dl> +<?bibhtml end?> +<?bibhtml bibdata bibrefs?> +<?bibhtml bibstyle plainhtml?> + +<p>See also the documentation for the <a +href="http://purl.org/nxg/dist/urlbst" ><code>urlbst</code> +package</a>, which generates BibTeX style files for ordinary LaTeX +output (which also supports a <code>@webpage</code> entry type, and +<code>url</code> and <code>lastchecked</code> fields), and which +contains a similar list of references concerned with citing online +sources.</p> + +<h2><a name='dist'>Distribution</a></h2> + +<h3><a name='changes'>Changes</a></h3> + +<dl> + +<dt>1.2, 2005 September 19</dt> +<dd><ul> +<li>Changes to <code>.bst</code> style files, adding +<code>@webpage</code> entry type, and <code>lastchecked</code> field +to all entry types.</li> +<li>Updates to documentation, fixing broken links to online references +discussing how to cite online sources.</li> +<li>No reports of breakage from beta releases below.</li> +</ul> +</dd> + +<dt>1.2b2, 2005 August 30</dt> +<dd><ul> +<li>Bugfix -- correctly escape characters in .bbl hrefs</li> +<li>Portability fix -- use <code>/usr/bin/env perl</code> at the top of the +script, rather than <code>/usr/bin/perl</code>; this should be more +portable.</li> +</ul> +</dd> + +<dt>1.2b1, 2005 August 19</dt> +<dd><ul> +<li>Use processing instructions such as +<code><?bibhtml start?></code>, rather than magic comments (the +old behaviour is still temporarily supported).</li> +<li>Add a new directive -- <code><?bibhtml insert?></code> +inserts the bibliography in-place.</li> +<li>Debugging output is now written to stderr rather than stdout.</li> +<li>Add <code>--help</code> and <code>--strip</code> options.</li> +<li>Documentation improvements.</li> +<li>Bugfix -- URLs are now properly escaped in the bibliography.</li> +</ul> +</dd> +</dl> + +<h3><a name='get'>Obtaining <em>bibhtml</em></a></h3> + +<p>Bibhtml is available on CTAN at +<a href="http://www.ctan.org/tex-archive/biblio/bibtex/contrib/bibhtml/" + ><code>biblio/bibtex/contrib/bibhtml/</code></a>, +and at +<code><a href="http://purl.org/nxg/dist/bibhtml" + >purl.org/nxg/dist/bibhtml</a></code>.</p> + +<p>Download the distribution: +<a href="bibhtml-1.2.tar.gz">bibhtml-1.2.tar.gz</a>.</p> + +<p>Do <a href="mailto:norman@astro.gla.ac.uk">let me know</a> if +you use this stuff. I'd be grateful for any bug reports, +and bug fixes, and also for any comments on the clarity or +otherwise of this documentation.</p> + +<h3><a name='licence'>Licence</a></h3> + +<p>This software is copyright, 1999, 2005, Norman Gray. It is released +under the terms of the GNU General Public Licence. See the copyright +declaration at the top of file <code>bibhtml</code>, and the file +<code>LICENCE</code> for the licence conditions. You can find an +online copy of the GPL at <code><a +href="http://www.gnu.org/copyleft/gpl.html" +>http://www.gnu.org/copyleft/gpl.html</a></code>.</p> + +<div class="signature"> +<a href="http://purl.org/nxg">Norman</a><br/> +2005 September 19 +</div> + +</body> +</html> |