• View
• Edit
• History
• Print

Typesetting

 

Given “suitable” Wikibook XML for citations, how should this be transformed into L^AT_EX and published?

     

PDF settings (show)

• parasep: space (separation between paragraphs)

1.  Challenge: the wiki defines the citation link text

In “normal” usage, L^AT_EX determines the text to use in a citation. The author writes \cite{key} and L^AT_EX uses the key to determine the cite text from the corresponding \bibitem{key} entry in the thebibliography environment. packages such as BIBT_EX and natbib can be used to augment the basic L^AT_EX functionality. In wiki usage, the wiki determines the appropriate citation text, so we need to instruct L^AT_EX not to do its normal processing.

The proposed solution is to generate the following XML:

   <cite kind=‘sic’ refid=‘key’>link text</cite>

We will transform this into the new L^AT_EX command \citesic[link text]{key} where the new command is defined to produce a link to the item in the bibliography corresponding to “key” using only the “link text”. The sic, meaning thus, indicates quoted text which may contain an error (although we expect the wiki to get it right).

This requires a DTD change to add ‘sic’ to the list of allowed values for the ‘kind’ attribute of the ‘cite’ element.

2.  Challenge: the wiki defines the reference text

In “normal” usage, L^AT_EX determines the sort order, citation numbering (if applicable), and reference text layout (including a suitable heading), for example by using BIBT_EX. In wiki usage, the wiki does this as part of rendering a page in HTML, so again we need to instruct L^AT_EX not to do its normal processing. The wiki produces 3 kinds of reference list, for a single page or page collection:

• items cited in the text, either numbered or in author–year mode
• an author–year bibliography, with no citations
• items cited in the text plus a bibliography of uncited items

The proposed solution is to generate the following XML for single pages:

   <references class=‘sic’><h level=‘1’>References for Page Name</h>
       …
   </references>

Or for page collections (illustrated for a single level page list):

   <references class=‘sic’><h level=‘1’>Bibliography</h>
       <h level=‘2’>References for Page Name 1</h>
       …
       <h level=‘2’>References for Page Name 2</h>
       …
   </references>

The output depends on whether the references are numbered, author–year, or a list of uncited references. It requires a DTD change to add:

• a bibliography element, containing (item)*
• bibliography to the allowed content of references

2.1  Numbered references

The proposed solution is to generate the following XML (“longestlabel” is the text of the longest label in the list):

     <bibliography style=‘longestlabel’>
         <item id=‘key’ style=‘label’>item text</item>
         …
     </bibliography>

Normally, ‘label’ contains the wiki-generated number. We will transform this into the following L^AT_EX code:

   \begin{thebibliography}{longestlabel}
       \bibitem[label]{key} item text
       …
   \end{thebibliography}

We need to redefine the thebibliography environment to suppress the automatically-generated heading.

2.2  Author–year references

The proposed solution is to generate the following XML:

     <bibliography>
         <item id=‘key’>item text</item>
         …
     </bibliography>

We will transform this into the following L^AT_EX code:

   \begin{abibliography}
       \abibitem{key} item text
       …
   \end{abibliography}

We need to define the abibliography environment and \abibitem command. By using 2 environments, we can support a numbered list of references and an author–year list, without redefining the \bibitem command.

2.3  Uncited references

The proposed solution is to generate the following XML:

   <p style=‘hanging’> item text </p>

In L^AT_EX, this should work like a normal paragraph hanging indent, with vertical space separating paragraphs. Alternatively, we could generate a bibliography block and items with no id, then transform this into an abibliography environment, with a variant of \abibitem without an id.

3.  Additional features

3.1  Formatting the item text

It is good practice to use extra horizontal space between the logical blocks of a reference, for example after the list of authors. To achieve this, we will:

• detect end of line continuation markers — the \ character
• transform these into <hspace dim=‘-’ /> XML (the ‘-’ is a new special case)
• transform these into \newblock T_EX commands

We need to make sure that \newblock works in paragraphs for uncited references, as well as in thebibliography and abibliography environments. Or put uncited references in an abibliography environment.

This requires no DTD change.

3.2  Book bibliographies

When typesetting the bibliography at the end of a book via the (:typeset-book:) directive, we need to change the opening tag to

   <references class=‘sic’><h level=‘0’>Bibliography</h>

We will transform this into

   \chapter*{Bibliography}

This preserves the book style and requires a DTD change to add ‘0’ to the list of allowed values for the ‘level’ attribute of the ‘h’ element.

4.  New wikibib.sty file

We will put the environment and command definitions required to support wiki-generated citations into a new wikibib.sty file. The style file will:

• define the \citesic[link text]{key} command
• redefine the thebibliography environment
• define the abibliography environment
• define the \abibitem{key} command
• possibly, define the \newblock command, as it appears not to work in some installations