diff options
author | Karl Berry <karl@freefriends.org> | 2007-12-23 23:54:09 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2007-12-23 23:54:09 +0000 |
commit | aaee78ecc72d37a1b2e1fd07a4014a4d37ac06ed (patch) | |
tree | 8a36b27b21b8218213a22ebe249799e750c95683 /Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html | |
parent | 07c67f147175961b6f70e7f2ea01301f68b9937c (diff) |
move bibhtml doc to bibtex
git-svn-id: svn://tug.org/texlive/trunk@5849 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html')
-rw-r--r-- | Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html | 522 |
1 files changed, 522 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html b/Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html new file mode 100644 index 00000000000..0c76961e2b1 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html @@ -0,0 +1,522 @@ +<?xml version="1.0"?> <!-- -*- nxml -*- --> + +<!-- $Id: bibhtml.html.in,v 1.10 2006/10/31 15:39:36 norman Exp $ --> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Bibhtml documentation</title> + <meta name="keywords" content="bibhtml, bibtex, HTML"/> + <link href="http://nxg.me.uk" rev="author"/> + <link type="text/css" + rel="stylesheet" + href="http://nxg.me.uk/style/base.css"/> + </head> + +<body> + +<h1>Bibhtml</h1> + +<div class='abstract'> +<p><em>Bibhtml</em> consists of a set of BibTeX style files, which +allow you to use BibTeX to produce bibliographies in HTML. As well, +it includes a Perl script which orchestrates the various steps +required to manage such a bibliography for one or more 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.3, 2006 October 31</em>.</p> +</div> + +<h3>Contents</h3> +<ul> +<li><a href='#usage'>Running <em>bibhtml</em></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='#options'>Supported options</a></li> +</ul></li> +<li><a href='#bst-files'>BibTeX style files</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 set of BibTeX style files, which +allow you to use BibTeX to produce bibliographies in HTML. As well, +it includes a Perl script which orchestrates the various steps +required to manage such a bibliography for one or more 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. To +use them, you should generate an <code>.aux</code> file by some +appropriate means, and include the line +<code>\bibstyle{plainhtml}</code>. Run BibTeX, and the result is a +<code>.bbl</code> file, in broadly the `plain' style, but formatted +using HTML rather than LaTeX. This might form a useful component of a +XSLT-based workflow. For further details, see the discussion of the +style files <a href="#bst-files" >below</a>.</p> + +<p>The <em>bibhtml</em> script can orchestrate generating and using +this <code>.aux</code> file, and you can specify the style file to use +either with the <a href="#opt-s"><code>-s</code> option</a>, or with +the processing instructions described <a href="#pis" >below</a>.</p> + +<h2><a name='usage'>Running <em>bibhtml</em></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="#options" >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='options'>Supported options</a></h3> + +<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='bst-files'>BibTeX style files</a></h2> + +<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> + +<p>The distribution includes a sample XSLT script, +<code>bibhtml.xslt</code> which shows how you might use XSLT to +extract citations from a source file into an <code>.aux</code> +file.</p> + +<p>The distributed <code>.bst</code> files have two configurable +parameters, which you might want to adjust for your installation:</p> + +<p>The variable <code>'xxxmirror</code> gives the host name of the arXiv mirror which will be used +when generating links to eprints. The default setting in the +<code>.bst</code> files is:</p> +<pre> +"xxx.arxiv.org" 'xxxmirror := +</pre> + +<p>By default, the style files generate link targets in the +bibliography with the same name as the citation key. Thus a BibTeX +entry with key <code>surname99</code>, say, would appear in the +generated HTML <code>.bbl</code> file wrapped in <code><a +name="surname99">...</a></code>. If this is inconvenient, +perhaps because it conflicts with other links within the file, +then you can adjust the <code>'hrefprefix</code> variable within the +style file, to specify a prefix which should appear in the link key. +Thus setting</p> +<pre> +"ref:" 'hrefprefix := +</pre> +<p>in the <code>.bst</code> file would produce links like <code><a +name="ref:surname99">...</a></code> in the <code>.bbl</code> +file.</p> + +<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.arxiv.org</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.3, 2006 October 31</dt> +<dd><ul> +<li>Add <code>hrefprefix</code> parameterisation to style files.</li> +<li><code>xxx.arxiv.org</code> is now the default e-prints host.</li> +<li>Some improvements to documentation.</li> +</ul> +</dd> + +<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 +<a href="http://purl.org/nxg/dist/bibhtml" ><code>@HOMEPAGE</code></a>.</p> + +<p>Download the distribution: +<a href="bibhtml-1.3.tar.gz">bibhtml-1.3.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/> +2006 October 31 +</div> + +</body> +</html> |