Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       hxcite-mkbib - expand references	and create bibliography

       hxcite-mkbib [ -b base ]	[ -p pattern ] [ -s separator ]	bibfile	[ file

       The hxcite-mkbib	commands copies	file to	standard output,  looking  for
       strings	of the form "[[label]]"	and for	a template for a bibliography.
       The label may not include white space and the  double  pair  of	square
       brackets	 must  enclose the label without any spaces in between.	If hx-
       cite-mkbib finds	the label in the bibfile, the string  is  replaced  by
       the  pattern.   The pattern can include certain variables. If the label
       is not found in bibfile,	it is left unchanged.

       The default pattern replaces the	string with a hyperlink, but if	the -p
       option  is  used, the replacement can be	any pattern. The input doesn't
       even have to be HTML.

       The file	consists of three parts:

       preamble	 The preamble is the part up to	the first  occurrence  of  %{.
		 The preamble is copied	to the output once (with bracketed la-
		 bels ("[[label]]") expanded). The character % is treated spe-
		 cially. To create a single % in the output, there must	be two
		 in the	preamble (%%). All other occurrences of	% followed  by
		 another  letter  are  not  copied,  but  are collected	into a
		 string	called the "sort order." and used to sort the entries,
		 as explained below.

       template	 The  template	starts	with %{L: and ends with	a matching %}.
		 The text in between is	copied as often	as there  are  biblio-
		 graphic  entries  in bibfile that correspond to bracketed la-
		 bels in file.	Variables in the template are replaced by  the
		 corresponding	field  in  the bibliographic entry: all	occur-
		 rences	of %x will be replaced by the field %x of  the	entry.
		 Parts of the text may be enclosed in %{x: and %}.  This means
		 that the text in between should only be output	if the current
		 entry	has  a field x.	 Text that is enclosed in %{!x:	and %}
		 will only be output if	the entry does not  have  a  field  x.
		 Both kinds of conditional sections may	also be	nested.

       postamble The  text after the %}	is copied unchanged to the output, af-
		 ter all bibliographic entries have been processed.

       By default bibliographic	entries	are copied to the output in the	 order
       of the labels in	file, except that labels that occur more than once are
       only used once. If the preamble contains	occurrences of %x (where x  is
       neither	"%"  nor  "{")	then  these together determine the sort	order.
       E.g., if	the preamble contains %A%D then	the  entries  will  be	sorted
       first on	field A	(author) and then on field D (date).

       Here  is	 an example of a file that creates a bibliography in HTML for-

	   ... text with [[references]]	here...
	   <!--%A%D sorted on author, then date	-->
	   <dt id="%L">%{A:A%}%{!A:%{E:E%}%{!E:%{Q:Q%}%{!Q:-%}%}%}</dt>
	     in: %{E:%E	(eds)
	     %}<cite>%B.</cite>%{V: %V.%}
	     in: %{E:%E	(eds)
	     %}<cite>%J.</cite>%{V: %V.%}%{N: %N.%}%{P:	pp. %P.%}
	     %}%{U:<a href="%U">%U</a>

       This template starts with four lines of preamble,  including  the  sort
       string  %A%D  on	line 3.	The sort string	itself will not	be output, but
       the rest	of the comment will.

       From the	line %{L: to the line %} is the	template. E.g.,	the line  that
       starts with <dt id=...  contains	a complex conditional text that	prints
       the authors (%A)	if there are any, otherwise the	editors	(%E) if	 there
       are any,	otherwise the institution that is the author (%Q), if any, and
       a dash otherwise.  Note how the parts are nested, Most of the  text  is
       inside  %{!A:...%},  meaning  that  that	part will only be effective if
       there is	no author field	(%A).

       The final two lines are the postamble and will  simply  be  copied  un-

       A bibliographic entry that looks	like this in bibfile:

	   %L Java
	   %A Gosling, James
	   %A Joy, Bill
	   %A Steele, Guy
	   %T The Java language	specification
	   %D 1998
	   %I Addison-Wesley

       will be printed by the template above as:

	   <dt id="Java">Gosling, James; Joy, Bill; Steele, Guy</dt>
	   <dd><cite>The Java language specification.</cite>
	     <a	href=""></a>

       The following options are supported:

       -p pattern
		 Specifies  the	 pattern  by which the string [[label]]	is re-
		 placed.  The pattern may include the variables	%b (which will
		 be replaced by	the value of the -b option) and	%L (which will
		 be replaced by	the label).  The default pattern is

		     <a	href="%b#%L" rel="biblioentry">[%L]</a>

       -b base	 Sets the value	for the	%b variable in the pattern.  Typically
		 this  is  set	to a relative or absolute URL. By default this
		 value is an empty string.

       -s separator
		 If there are multiple authors or editors in an	 entry,	 their
		 names	will be	listed with a separator	in between. By default
		 the separator is "; " (i.e., a	semicolon and a	 space).  With
		 this option the separator can be changed.

       The following operands are supported:

       bibfile	 The  name  of a bibliographic database	must be	given. It must
		 be a file in refer(1) format and every	 entry	must  have  at
		 least	a %L field, which is compared to the bracketed labels.
		 (Entries without such a field will be ignored.)

       file	 The name of the input file is optional. If absent, hxmkbib(1)
		 will read the template	from stdin.

       The following exit values are returned:

       0	 Successful completion.

       > 0	 An  error  occurred. Usually this is because a	file could not
		 be opened or because the %{ and %}  pairs  are	 not  properly
		 nested.   Very	 rarely	it may also be an out of memory	error.
		 Some of the possible error messages:

       missing ':' in pattern
		 hxmkbib found a %{ but	the second or third  letter  after  it
		 was not a colon.

       no '%{' in template file
		 The  template	file  is unusable, because it contains no tem-

       unbalanced %{..%} in pattern
		 There are more	%{ than	%}.

       asc2xml(1),  hxcite(1),	hxmkbib(1),  hxnormalize(1),   hxnum(1),   hx-
       prune(1), hxtoc(1), hxunent(1), xml2asc(1), UTF-8 (RFC 2279)

       Sorting is primitive: the program doesn't parse dates or	names and sim-
       ply sorts "Jan 2000" under the letter "J" and "Albert Camus" under  the
       letter  "A". For	the moment the only work-around	is to put names	in the
       bibfile as "Camus, Albert".

       The program simply lists	all authors or editors.	There  is  no  way  to
       generate	 an  "et.  al."	after the third	one. The work-around is	to put
       the "et.	al." in	the bibfile.  Putting commas between the first authors
       and the word "and" before the final one is also not possible.

       The  program  doesn't  try to interpret names of	authors	or editors and
       they cannot be reformatted. It is impossible to write a	name  that  is
       specified  as  "Sartre,	Jean-Paul" in the bibfile as "J. Sartre" or as
       "Jean-Paul Sartre" in the output.

       There is	no way to suppress a period after a field if the field already
       ends with a period. E.g., the template "%{A:A.%}" may generate "A. Per-
       son Jr.." if the	author is "A. Person Jr." The only option is to	either
       not put periods in the bibfile or not put periods in the	template.

       Entries	in  the	 bibfile  can  only  be	used if	they have a %L (label)
       field. The program cannot find entries by searching for keywords,  like

       hxmkbib	will replace any ampersands (&)	and less-than (<) and greater-
       than (>)	signs that occur in the	bibfile	by their  XML  entities	 &amp;
       &lt; &gt; on the	assumption that	the template is	HTML/XML. This may not
       be appropriate for other	formats.

       hxcite-mkbib is a (bash)	shell script that calls	 hxcite(1)  and	 hxmk-
       bib(1), and is therefore	not portable to	all platforms.

7.x				  10 Jul 2011		       HXCITE-MKBIB(1)


Want to link to this manual page? Use this URL:

home | help