summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/bibhtml/bibhtml.html
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/bibhtml/bibhtml.html')
-rw-r--r--Master/texmf-dist/doc/latex/bibhtml/bibhtml.html479
1 files changed, 479 insertions, 0 deletions
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>&lt;a href="bibliography.html#grendel89"&gt;(Grendel, 1989)&lt;/a&gt;</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>&lt;?bibhtml start ?&gt;</code>
+and
+<code>&lt;?bibhtml end ?&gt;</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>&lt;-- bibhtml start
+--&gt;</code> and <code>&lt;-- bibhtml end --&gt;</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>&lt;?bibhtml insert?&gt;</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>&lt;?bibhtml bibdata </code><em>bibfile</em><code>?&gt;</code>
+and <code>&lt;?bibhtml bibstyle</code><em>stylefile</em><code>?&gt;</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>&lt;?bibhtml today ?&gt;</code> with today's date.</p>
+
+<p>Summary of processing instructions:</p>
+
+<dl>
+<dt><code>&lt;?bibhtml start?&gt;</code> and <code>&lt;?bibhtml
+stop?&gt;</code></dt>
+<dd>Bracket the bibliography -- any text between these PIs is replaced
+when <em>bibhtml</em> is next run.</dd>
+
+<dt><code>&lt;?bibhtml insert?&gt;</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>&lt;?bibhtml bibdata </code><em>bibfile</em><code>?&gt;</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>&lt;?bibhtml bibstyle </code><em>stylefile</em><code>?&gt;</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>&lt;?bibhtml today?&gt;</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>&amp;nbsp;</code>, and <code>--</code> to
+<code>&amp;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>&lt;?bibhtml
+bibdata xxx?&gt;</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>&lt;?bibhtml
+bibstyle xxx?&gt;</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&amp;arg2=one;two&amp;moreargswhichmaketheurlquitelong"
+>bibhtml tests - how do we handle odd ( &amp;)
+ 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>&lt;?bibhtml start?&gt;</code>, rather than magic comments (the
+old behaviour is still temporarily supported).</li>
+<li>Add a new directive -- <code>&lt;?bibhtml insert?&gt;</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>