Difference between revisions of "Bibliographic/Writer enhancements for OOBib"

Revision as of 22:22, 30 March 2006

This document has been placed on the wiki so that members of the OpenOffice community can assist in developing the design and documentation for the enhanced bibliographic facility. Please feel free to add, correct or improve this document.

Introduction

Enhancements of the bibliographic facility are considered in three parts.

• There is the Citeproc formating engine which performs the formating of citations and reference tables according to the style selected by the user. (See a diagram of the components.)

• There are the enhancements need to the OpenOffice word-processor 'Writer' to support the Citeproc formating engine.

• Then there are the enhancements needed Writer to better support the different types of document styles in common usage. This document details the latter two sets of enhancements.

Backwards and Forwards Compatibility

An important object of Bibliographic Enhancement project is to maintain document file backwards compatibility with older versions of OpenOffice. To achieve this when Bibliographic Entries are inserted into a Document they are stored in the same format as is currently the case in OOo 2.0.x. A new bibliographic entry tag will be added with the enhanced citation functions, and each citation will contain a key that will point to the bibliographic data which will be saved in the document save package. To preserve backwards compatability we will also need to maintain the old bibliographic citation and data storage in the document. Older versions of OpenOffice (1.1.5 and 2.0.x) without the bibliographic enhancements, will read the old format of the bibliographic citations and ignore the bibliographic data file in the save package. A suggested approach is illustrated in a flowchart.

When a major revision of the save package format is introduced, support for the older bibliographic representations can be dropped from the document save file.

Changes to Writer XML file format

We need to change the method of storing citations in the XML file format. Currently when a citation is inserted into a document, all the citation details are stored with the citation mark. If there are many citations to the same work, the details will be stored many times in the document. If an error is discovered with the citation, such as a spelling error or incorrect page number reference, the only direct way to fix this is to correct the bibliographic database record, delete and reinsert all the references or to extract the saved file and attempt a global find and replace to correct the error. None of these methods is satisfactory. The solution to this problem is to store the bibliographic record only once in the document, and provide each citation in the text with a link to that bibliographic record. Any changes to a citation would only need to be made to the single bibliographic record. The bibliographic record should also store a link to its database source, so that changes to the bibliographic database could be automatically updated in the document using the Tools->Update->Links function. See the Bibliographic Developer's page for more details.

Support for Document Style selection

The Writer GUI interface needs an enhancement to support Document Style selection, saving and loading. The document file format should have a Current Document Style field added which would contain the Current Style Name. The Document Style selection GUI would provide a list of the installed Document Style Packages (see next section). Other options would be to Import and Export Document Style Packages.

The current facilities support only one default document style. Document style selection should apply to the whole document. Some styles such as MLA's Research Paper defines line spacing, margins and headings etc and these settings should be supported as well. Also there are options within styles. For example, an other bibliographic software package provides the following options for The MLA Handbook version 4 -

• Document Type-
  • Article (Non-anonymous Review)
  • Article (Masked/Anonymous Review)
  • Chapter in Manuscript At [ ] (number)
  • Chapter in Dissertation/Thesis At [ ] (number)
  • Student research Paper

• Heading Numbering System-
  • 1, 1.1, 1.3, etc.
  • Level 1 always A; Level 2 always B (in 1st edition)
  • Level 1 is [1] [2]; Level 2 is 1.1 (in 1st edition)

• Note types-
  • Footnote
  • Endnote

• Include elements-
  • Preliminary Text
  • Back Matter

The Document Style package contents.

The Document Style Package would contain the following information-

• The Style full name, and version number.
• The user selectable style options.
• Name of macro to set up document formating options (margins, headings etc.)
• Rules defining the automated treatment repeating footnote references with 'Ibid' or 'op cite' (etc.)
• The bibliographic table sorting library name (to select the sorting module).
• The datasource specification which contains an XPATH statement pointing to the file or database that contains the bibliographic records. (Citporc can 'include' this statement).
• The name of Citproc package of xslt code-sheets to produce -
  • In-text citations
  • Footnote initial citations
  • Footnote subsequent citations
  • Endnote initial citations
  • Endnote subsequent citations
  • Bibliographic table entries

New Field and Insert menu item 'Quotation'

Add a new Insert menu item 'Quotation'. This would paste the current clipboard item into the document and tag it with bibliographic source data using the same or similar dialog as Insert->Indexes and Tables->Bibliographic Entry->New. There should be a (user configurable) method of highlighting quotation text and objects, for example, with color underlining or highlighting. It would have an appropriate context menu to allow the editing of the bibliographic source data. Quotation objects would have an option to display the attached citation or not according to the current style. Quotations would also have the ability to assign a style to that text. There would also be a new Indexes/Table type – 'Quotations'. Which would be very similar to the Bibliographic Table but would also have the object type as field ie. Text, graphic, chart, drawing etc.

The attributes of the Quotations in a document should also be available in the Cross-reference facility.

How high a priority isthis feature? It sounds great but I'm not sure how necessary it is. Also I'm not sure that this is the optimal UI -- for instance, I often have to type in quotes from some written source. Under this method, I guess I would type in the quote, Cut the newly-typed text, and then Paste the same text using the 'Quotation' command. Seems counter-intuitive; why don't I just typethe text, highlight it, and then choose 'mark Selection As Quotation'? --MattPrice

Support for the footnote citation style

Support needs to added for the footnote citation style (commonly used in the Humanities, and particularly in History) such as defined in the Chicago Manual of Style. Eg.

34. Thomas M. Charles-Edwards,"Honour and status in Some Irish and Welsh Prose Tales.", Eriu, xxxvi, 1978. 35. Charles-Edwards, loc. cit., page 325. 36. ibid.

NOTE: Some styles prefer ibid, (for ibidem, "in the same place") in stead of op. cit and loc. cit.

THis is a feture I very greatly desire. How hard will it be to implement? I was under the impression it was a showstopper. If so, can wethink ofthis as a logner-term goal? --MattPrice

Different treatment for first and subsequent uses of the citation. There needs to be provision for user selection for, and the defining of citations and references with different treatment for first and subsequent uses of the citation.

There is a tedious and fault prone aspects of the footnote / endnote citation method - the maintenance the Initial and Subsequent citations in the correct order as one edits the text. It is not difficult when editing to move a piece of text and have as result the Initial Citation reference coming after the Subsequent reference. An automated process would ensure these errors do not occur.

Ibid

There needs to be support for the automated treatment repeating footnote references such as the use of 'ibid' (or 'op cit' or 'loc. cit') depending on style.

Handling of other text in footnote citation support

In designing the footnote citation support consideration needs to be take of the handling of other (non-bibliographic citation) text in the footnote, when the user changes the document style form footnote to in-text citation. In general the user text would remain in the footnote when the citation was moved to in-text. But the Insert->Bibliographic dialog would need to allow the user to tag or insert text what was to be a suffix of a prefix to the citation whatever citation method was selected. When this was used then, if no other text was in the footnote, then all the text would be moved in-text with the new citation format and the footnote deleted.

Citation types to be supported

Chicago Manual of Style (and possible other style manuals) specify different formats for footnote and endnote citations and the bibliographic table (citation use Initials & Surname, Bibliography Table uses Surname & Initials). So we need to define formats for

• In-text citations
• Footnote initial citations
• Footnote subsequent citations
• Endnote initial citations
• Endnote subsequent citations

User selectable footnote and endnote location

There needs to be an option to place the document wide footnotes and endnotes an a user selectable location. Currently, for endnotes, there are only two options available at the end of the document or at the end of each section. For footnotes there are two options for Position='End of Page' or 'End Of Document'. A new option needs to be provided to allow for a user selectable location for both. Perhaps this could be implemented with a new option in Format->Sections to include an check box with -

"[ ] Place Document Endnotes at the end of this section" and "[ ] Place Document Footnotes at the end of this section".

Only one section in each document should have each setting.

The reason this needs to be made more flexible is that style manuals specify different locations. For example the formatting guidelines for APA and Chicago style submissions specify the following order for the sections in a document:

APA Style 
  title page 
  abstract 
  text 
  references 
  appendixes 
  author note 
  footnotes/endnotes 
  tables 
  figure captions 
  figures 

Chicago Style (back matter) 
  Appendix 
  Endnotes 
  Glossary 
  Bibliography 
  Index 
  Colophon 

See issue number 37679 for details.

Note: Whilst Bibliographic citations can be in-text, footnote or endnote types. The user should still be able to – when using footnote citations use endnotes as well and when using endnote citations use footnotes as well. To support this properly there should be provision for Footnote symbols. The Chicago Manual of Style, 15th ed. section 16.63 p 609, stipulates that when Endnotes and Footnotes are both used, the Endnotes are consecutively numbered (1,2,3 ...) and the footnotes referenced by symbols. The symbol series they suggest are - and as more symbols are needed they are doubled and trebled - .

Endnotes and footnotes enhanced to enable the first note to be un-numbered

The proposal is to add a user option so that the first footnote or endnote in the current series is not numbered. This may seem strange but is a common practice in journals or multi-author works. (Issue 50217).

The Chicago Manual of Style, 15th edition, section 16.66-16.70, pages 610-612, describes this requirement -

"Unnumbered footnotes always precede any numbered notes on the same printed page. They are most often used even when the numbered notes are endnotes. Unnumbered endnotes [...] should appear immediately before note one of each chapter."

"In Journals or multi-author works, special acknowledgements may be given in an unnumbered footnote on the first page of an article or chapter., sometimes appended to the bibliographic information." [Example unnumbered note -]

'The authors gratefully acknowledge the assistance of Oscar J. Blunk of the National Cyanide Laboratory in the preparation of this paper.'

An implementation suggestion – That this done by optionally allowing notes series to begin with a zero numbered note which would always have the zero number suppressed in the display.

Enhanced Heading Support for Endnotes

The currently the Endnotes are presented as a solid block of notes at the end of the document or chapter. The Chicago Manual of Style, 15th edition, section 16.60, p 608, Running heads for notes sections, recommends that Endnotes be separated by their relevant Chapter Headings and preferably with the related Page Range in the header of the Notes section. So that the header could contain -

    Notes to pages 245-268

To support this, the Endnotes settings Panel (Tools->Footnotes->'Endnotes tab') needs to have a "Counting" selection with "Per Page, Per Document and Per Chapter", as is in the footnotes options. (Issue 50220).

Insert citation options

The Insert-> Bibliographic Entry will need to provide for different citation options provided by the style. For example, one Style (I am not sure which but at a German University) requires the following – In quoting a document(book/journal/article etc.) without a page it looks like

"This method is very reliable (AUTHOR YEAR)"
or
"But AUTHOR (YEAR) showed that..."

If a page or some pages are quoted (direct or indirect) it must look like
"'This method is very reliable' (AUTHOR YEAR:12)"
f.e. "'This method is very reliable' (BASLER 2003:12)"
or
"'This method is very reliable' (BASLER 2003:12 ff.)"
or
"AUTHOR (YEAR:12) stated 'This method is very reliable.'"
f.e. "BASLER (2003:12) stated 'This method is very reliable.'"
or
"BASLER (2003:12 f.) concludes that this method is very reliable.'"
Some comments on that:
1. The AUTHOR(s) must be in small capitals (as every person everywhere in the text).
2. One author: "AUTHOR 2003" Two authors: "AUTHOR1 & AUTHOR2 2003" Three or more: "AUTHOR1 ET AL. 2003"
If there are more than one publication of an author in the same year it must look like:
"BASLER 2003a" and "BASLER 2003b" a.s.o.

To summarize, the citation options for this style are:

[Author | Author & Author | Author et al.] (YEAR{x}:page {f. | ff.})

or

([Author | Author & Author | Author et al.] YEAR{x}:page {f. | ff.})

Note: 'f.' means 'and the following page' and 'ff.' means 'and following pages'.

Other variants include multiple references within the citation brackets. eg. (Doe, 1999, 2000; see also Jones 1998; Smith 2000) Depending upon the style multiple references may be shortened. (Doe, 1999a; Doe, 1999b) to (Doe, 1999a, b) This could implemented as an automatic merging of neighboring citations. The citation implementation needs to support text between the Author name, some free text and the actual date citation.

According to Doe, "X, Y, Z" (1999:23) Where "X, Y, Z" is a comment about the text eg

Carney holds the view that there was a strong influence of Classical epic 
on the written Irish tales in (1986:128). 

The same support is required in footnote citations:

34. Carney holds the view that there was a strong influence of Classical epic 
     on the written Irish tales in "The History of Early Irish Literature: 
     The State of Research”, 128.

Note: There has been some discussion regarding limiting the free text between the beginning and end part of the citation. Two suggestions are - to limit the text to one sentence – that is the end part of the citation would be placed before any full stop. Alternatively, the text could be limited to a single paragraph. More than this does not seem very sensible.

Bibliographic attributes should be available from the Cross-reference facility

It would be useful if bibliographic references and their data fields were accessible in the Cross-reference tool.

The proposal is to add document's Bibliographic entries as a new reference type into the Cross-reference 'References' tab. (See the panel design below.) When the proposed 'Bibliographic Entries' reference type was selected the Selection panel would show the bibliographic entries in the document by listing the Identifier (Short name). When a particular record was selected, the Format panel would show the all fields of the bibliographic record, together with the current sequence number of the citation – that is the number that is shown when numbered citations as listed.

See issue 49050.