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

FreeBSD Manual Pages


home | help
HXMKBIB(1)			HTML-XML-utils			    HXMKBIB(1)

       hxmkbib - create	bibliography from a template

       hxmkbib	[ -s separator ] [ -a auxfile ]	[ -n maxauthors	] [ -r moreau-
       thors ] bibfile [ templatefile ]

       The hxmkbib commands reads a list of bibliographic keys	(labels)  from
       auxfile,	 finds the corresponding entries in bibfile and	creates	a bib-
       liography, using	templatefile as	a model. The auxfile may,  e.g.,  have
       been  created  by  hxcite(1).  It consists of labels, one per line. The
       bibfile is a refer(1) style database.  hxmkbib looks for	entries	with a
       %L field	equal to a key in the auxfile.

       The templatefile	consists of three parts:

       preamble	 The  preamble	is  the	part up	to the first occurrence	of %{.
		 The preamble is copied	to the output  unchanged,  except  for
		 occurrences  of %.  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 use	 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 keys in aux-
		 file.	Variables in the template are replaced by  the	corre-
		 sponding field	in the bibliographic entry: all	occurrences 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 keys in auxfile,	except that keys 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 template file that	creates	a bibliography in HTML

	   <!--%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:

       -a auxfile
		 The  file  that  contains the list of keys (labels) for which
		 bibliographic entries should be printed. If the option	is ab-
		 sent,	the  name of this file is formed from the templatefile
		 argument by removing the last extension and adding .aux.   If
		 no templatefile is given, the default auxfile is aux.aux.

       -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.

       -n maxauthors
		 If there are more than	maxauthors authors in an  entry,  only
		 the  first  author will be printed and	the others will	be re-
		 placed	by the string moreauthors.  The	default	is 3.

       -r moreauthors
		 The string to print if	there are  more	 than  maxauthors  au-
		 thors.	The default is "et al.".

       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 used as key. (Entries without such
		 a field will be ignored.)

		 The name of the input file is optional.  If  absent,  hxmkbib
		 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), hxnormalize(1), hxnum(1),	hxprune(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.

7.x				  10 Jul 2011			    HXMKBIB(1)


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

home | help