From 754d87c1ab6482f6628142cac6b94c783e36c1c7 Mon Sep 17 00:00:00 2001 From: Manuel Pégourié-Gonnard Date: Fri, 20 Nov 2009 10:08:07 +0000 Subject: bibhtml update: version 2.0.1, released 2009 November 2 git-svn-id: svn://tug.org/texlive/trunk@16093 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html | 95 +++++++++++++---------- 1 file changed, 54 insertions(+), 41 deletions(-) (limited to 'Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html') diff --git a/Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html b/Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html index ae24e497a0c..d68dfd94d81 100644 --- a/Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html +++ b/Master/texmf-dist/doc/bibtex/bibhtml/bibhtml.html @@ -4,7 +4,7 @@ Bibhtml documentation - + @@ -20,10 +20,10 @@ modelled closely on the standard BibTeX style files.

which illustrate how you might integrate these generated bibliographies into an XML/HTML workflow.

-

The long-term URL for this page is http://purl.org/nxg/dist/bibhtml

+

The long-term URL for this package is http://purl.org/nxg/dist/bibhtml

This documentation describes -bibhtml version 2.0, released 2009 August 9.

+bibhtml version 2.0.1, released 2009 November 2.

Contents

@@ -40,21 +40,22 @@ bibhtml version 2.0, released 2009 August 9.

Bibhtml consists of a set of BibTeX style files, which allow you to use BibTeX to produce bibliographies in HTML. These are -modelled closely on the standard BibTeX style files.

+modelled closely on the standard BibTeX style files. For sample output, +see the reference section below.

To accompany them, this package includes a pair of XSLT scripts which illustrate how you might integrate these generated bibliographies into an XML/HTML workflow.

The output of these style files is usable as-is, but it benefits -from some post-processing, to remove TeX-isms. There's a sed +from some post-processing, to remove TeX-isms. There’s a sed script in the distribution which does exactly that, called detex.sed. If you want to make a version of that im some other regexp-supporting language, let me know and I can include it in the distribution.

As well, -it includes a Perl script which orchestrates the various steps +the package 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 @@ -78,7 +79,7 @@ XSLT-based workflow. For further details, see the discussion of the style files below.

There is also a Perl script, bibhtml, which can orchestrate generating and using -this .aux file. This script isn't really maintained any +this .aux file. This script isn’t really maintained any more, but it is still distributed, and documented below.

Bibhtml works with a standard BibTeX database -- it is @@ -93,9 +94,14 @@ archive, this will be of no interest to you.

BibTeX style files

The package includes several BibTeX style files. As well as the -ones directly derived from the standard styles, there are also plainhtmldate.bst and -plainhtmldater.bst, which are derived from the standard -plain.bst which sort the +ones directly derived from the standard styles, there are also +plainhtmldate.bst, +plainhtmldater.bst, +alphahtmldate.bst and +alphahtmldater.bst styles, +which are derived from the standard +plain.bst and alpha.bst styles, +which sort the output by date and reverse date, rather than by author.

In version 2 of the bibhtml package, the @@ -191,7 +197,7 @@ reasonably usable without any post-processing. However it is not ideal, since there are occasionaly TeX-isms such as backslash-escaped characters and the like, depending on what is in the source .bib file. Also, without post-processing any DOIs in -the source file aren't formed into links.

+the source file aren’t formed into links.

The distribution includes a sed file, detex.sed, which can do appropriate post-processing. @@ -203,28 +209,31 @@ Thus the normal workflow is:

Since it uses sed, this is fairly obviously unix-specific, but if anyone would like to contribute a script with -similar functionality (it's just a few moderately tortuous regular -expressions), I'd be delighted to include it in the distribution.

+similar functionality (it’s just a few moderately tortuous regular +expressions), I’d be delighted to include it in the distribution.

Installation

The .bst files have to be installed -‘somewhere where LaTeX can find them’. If you give the command +‘somewhere where LaTeX can find them’. If you give the command kpsepath bst you can see the list of directories that -BibTeX searches for .bst files – on my system, I'd put +BibTeX searches for .bst files – on my system, I’d put them into /usr/local/texlive/texmf-local/bibtex/bst, which is a directory for system-wide local additions.

If you wish, you may change the distributed BibTeX style files (see above) to the extent of changing the -`eprint' mirror site from the master xxx.arxiv.org to a -more local mirror. If you don't use the LANL preprint archive, this +‘eprint’ mirror site from the master xxx.arxiv.org to a +more local mirror. If you don’t use the LANL preprint archive, this will be of no interest to you.

The bibhtml script

-

As noted above, this script should still work and is distributed on -that basis, but it's no longer maintained, and won't be further developed.

+

As noted above, this script should still work and is distributed on +that basis, but it’s no longer maintained, and won’t be further developed. +The XSLT-based mechanism described above is probably more robust; +also, the interface described in this section is not the same as the interface +of the XSLT scripts section above.

The BibTeX database

@@ -241,7 +250,7 @@ with these in future versions.

composed of the BibTeX citation key. Thus, you might cite [grendel89] with

<a href="bibliography.html#grendel89">(Grendel, 1989)</a>
-

(of course, the link text can be anything you like). That's all there is to +

(of course, the link text can be anything you like). That’s all there is to it. When you run bibhtml, it generates an .aux file which makes BibTeX produce references for exactly those keys which appear in this way.

@@ -258,7 +267,7 @@ and <?bibhtml end ?> (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 +this file is set up, you shouldn’t have to touch it again. Older versions of bibhtml used the magic comments <-- bibhtml start --> and <-- bibhtml end -->: these are still supported, but are deprecated and may disappear in a future version.

@@ -275,12 +284,12 @@ example), which will not therefore have to be rescanned in future.

the command line (see below) or using the <?bibhtml bibdata bibfile?> and <?bibhtml bibstylestylefile?> 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 +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.

As a special case, bibhtml also replaces the line after a -comment <?bibhtml today ?> with today's date.

+comment <?bibhtml today ?> with today’s date.

Summary of processing instructions:

@@ -307,7 +316,7 @@ of \bibliographystyle{stylefile} command in a LaTex file; see also the -s command-line option.
<?bibhtml today?>
-
Replace the following line by today's date.
+
Replace the following line by today’s date.

Supported options

@@ -332,17 +341,17 @@ whatever has been specified as the bibliography file name.

Set this to +3 if you want ~ translated to &nbsp;, and -- to &enspace;. Or set it to -3 (the default) if you -don't.
+don’t.
-a
-
If this option is set, bibhtml won't bother scanning any +
If this option is set, bibhtml won’t bother scanning any files at all, and will generate references for all the entries in your database. This is equivalent to \nocite{*} in LaTeX.
-b bibdata
The name of your BibTeX database file, as it would be specified in a \bibliography{} command in LaTeX. Unless you happen to -keep all your references in a file called bib.bib, you'll +keep all your references in a file called bib.bib, you’ll probably want to change this. Or you can use the <?bibhtml bibdata xxx?> processing instruction.
@@ -353,7 +362,7 @@ options, which are inserted in the command line at that point.
--merge
In this special case, bibhtml takes two arguments, a .bbl file and an .html file, -merges the first into the second, and nothing else. It's +merges the first into the second, and nothing else. It’s intended to be used when you have generated a .bbl file by a separate run of BibTeX, and simply wish to merge the results into your bibliography file. As @@ -361,15 +370,15 @@ such, it will most likely be useful as part of a script, or other post-processing system.
-r rootname
-
Specify this and you'll create rootname.html, +
Specify this and you’ll create rootname.html, rootname.aux and so on. Why not just stick with the default -`bibliography'...?
+‘bibliography’...?
-s bibstyle
The name of the BibTeX bibliography style you want to use, as it would be specified for the \bibstyle command in LaTeX. If you want to have a different layout for your HTML -bibliographies, please don't change the file plainhtml.bst +bibliographies, please don’t change the file plainhtml.bst distributed with bibhtml. Instead, make a copy of plainhtml.bst under a different name, edit it as much as you like, and use this option of bibhtml to use the modified @@ -392,8 +401,8 @@ verbose.

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 +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 @@ -426,9 +435,10 @@ platforms. If so, please get in touch, with suggestions.

Example

There are multiple sources of advice for how to cite electronic -documents. The most formal are an ISO standard url:iso690, and the American Psychological -Association's guidance in Sect. 6.31 of apastyle. As well, there are older, but still -useful discussions in walker06 and emory95.

+documents. The most formal are an ISO standard url:iso690, and the American Psychological +Association’s guidance in Sect. 6.31 of apastyle. As well, there are older but still +useful discussions in walker06 and +emory95.

References

@@ -474,11 +484,11 @@ and at http://purl.org/nxg/dist/bibhtml.

Download the distribution: -bibhtml-2.0.tar.gz or -bibhtml-2.0.zip.

+bibhtml-2.0.1.tar.gz or +bibhtml-2.0.1.zip.

Do let me know if -you use this stuff. I'd be grateful for any bug reports, +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.

@@ -501,6 +511,9 @@ online copy of the GPL at h
+
2.0.1, 2009 November 2
+
The *date.bst and *dater.bst styles now work again.
+
2.0, 2009 August 9
First real release of v2.0, after mild use elsewhere.
@@ -555,7 +568,7 @@ inserts the bibliography in-place.
Norman
-2009 August 9 +2009 November 2
-- cgit v1.2.3