[pmwiki-users] Bibliographies (directive options)

John Rankin john.rankin at affinity.co.nz
Thu Sep 14 18:49:52 CDT 2006

On Friday, 15 September 2006 2:38 AM, christian.ridderstrom at gmail.com wrote:
>On Thu, 14 Sep 2006, John Rankin wrote:
>> On Wednesday, 13 September 2006 10:01 PM, christian.ridderstrom at gmail.com wrote:
>> >
>> >If (:bibtex:) renders a bibliography, why not call it (:bibliography:), or 
>> >am I missing something here?  (I doubt the casual author will know what 
>> >BibTeX is)
><snipped and placed first>
>> But mostly, I haven't really thought about what markup to use yet,
>> and was just using (:bibtex:) as an illustration...
>As an illustration it is fine... but let me verify that I understood it 
>correct when I think that (:bibtex:) was meant to render as the 
>bibliography? In other words (:bibtex:) is the directive that will result 
>in the bibliography being shown at the place where the author placed the 
>(We might end up introducing something like (:bibtex:) ... (:bibtexend:) 
>in order to clearly deliminate where the BibTeX markup can be

(long post follows)

This is a key question so merits a dedicated response. I'll try to
make what's in my head visible (it needs a whiteboard). Please treat
this as a thought-experiment / set of hypotheses to be tested.

To answer the question directly: no; the (:bibtex:) directive is
an instruction that says "this page has a bibliography; place it
where the output template instructs you to place it".

I think the discussion needs to separate "what" from "how" and
start with the logical structure of a document that includes a
list of references. How that structure is translated into an
HTML page or a LaTeX document is a question for later.

I draw heavily on Christian's use cases, documented at

Case 1. an article

An article consists of (at least) title, author, date,
introductory matter, one or more sections, and references. 

References can be displayed in a number of possible ways:

- as a footnote to the page on which the citation appears
  (usually "[n]" citation style)

- as a list of endnotes to the document, either in 
  citation order ("[n]" citation style) or alphabetic
  order ("Name (year)" citation style)

- as footnotes ("[n]" citation style) *and* an alphabetic 
  list of endnotes 

See: http://www.wikipublisher.org/wiki/index.php?n=Wikibook.Article

Case 2. a book

A book consists of (at least) front matter (title, author,
subtitle, date, legal notice, and book metadata), main matter
(chapters, including chapters like a preface and colophon,
and appendices), back matter (references, index)

References are normally listed in alphabetic order, after the
appendices and before the index.

See: http://www.wikipublisher.org/wiki/index.php?n=Wikibook.Book

For a (test for illustration; references not included) sample:

Press 'Typeset book', then 'Download'. (The 'LaTeX' button 
doesn't do anything as yet)

Case 3. a stand-alone bibliography

This is a list of references, possibly annotated, designed to
be read and used as a distinct document -- e.g. a recommended
reading list. The references may or may not be cited in an
associated article or book.

Cutting to the chase (intermediate logic left as an exercise 
for the interested reader)...

My hypothesis is that a (:bibtex:) directive (however it may
be implemented) usually just needs to insert an array item

    $XMLFooter['references'] (= & $HTMLFooter['references'])

This will allow precise control over where and how references
get inserted in the output xml stream, with suitable tags.
In HTML, this would be the bibliography rendered into html
markup, whether for a single wiki page or multiple pages; 
in wikibook, it would be a pointer to the bibtex source, 
which LaTeX will subsequently process.

I believe this can be implemented and will work to meet the 
requirements as I understand them. What I don't understand
is whether it can be implemented using (:pagelist:), as has
been suggested. Specifically: how would one use (:pagelist:) 
to insert

  <references bibfile='http://path.to.Group.BibliographyDb'>
  text that is a preamble to the bibliography and hence
  may include translated wiki markup</references>

inside the <backmatter> tag in the book example above.

A bit of background: anything output as a wiki page is
inside <frontmatter><chapter>...</chapter></frontmatter>.
It's relatively easy to do if (:bibtex:) sets an item
in $XMLFooter, via the book's trail page, as <backmatter>
contains <!--FooterText-->, just as <frontmatter>
contains <!--HeaderText-->.
John Rankin

More information about the pmwiki-users mailing list