Difference between revisions of "Bibliographic/Developer Page/API Enhancements"

Revision as of 21:25, 24 September 2006

This page is very much under construction and we would appreciate assistance in making it better.

Details of the current Bibliographic implementation and API reference documentation is available here. For an overview of Write and Citproc (the bibliographic formatting engine) interaction see Citeproc_Writer_Interaction

Terminology

For clarity, this project deals with the following pieces:

citation

a short description that points to a fuller description elsewhere, either in a note or a reference list. Called a 'bibliographic entry' in most of the OOo documentation.

reference item

a fuller description; also called a bibliographic entry or item

reference list

a collection of references; also called a bibliography

Introduction

Diagram showing the relationship between Service BibliographicCitation Service Bibliography and other key Writer services.

Notes:

• The interface named "Metadata & user defined data access interface" refers to the proposed interface to support the new ODF metadata enhancements expected in the release of ODF 1.2 next year.

• The 'Extension Development Toolkit' (announcement pdf, video, home page) will:
  • Be able to implement OpenOffice.org extensions with appealing GUI look and feel.
  • Provide smart integration in OpenOffice.org help system.
  • Provide smart integration in “Tools / Options” dialog.
• CiteProc refers to the Bibliographic formatting engine developed by Bruce D'Arcus [1].

Service BibliographicCitation

This is a new service to support the enhanced bibliographic features. It main function is the screen presentation and handling of Bibliographic citation field. It's function include:

• Insertion of citation marker (footnote / endnote or in-text) and the selection of citation options.
• Visual marking of the citation field and its components.
• The automatic selection of initial, subsequent and Ibid citation forms
• The display of context menus
• The acceptance and display of citation options.

constants group BibliographyDataField

com :: sun :: star :: text ::

Stores the contants for the new Service BibliographicCitation (described above).

Description

This constants group needs to be totally rewritten. The old definition was

“These values define parts of bibliographic data. They are used to create a
bibliography in a text document.”

The new definition is:

These values define the characteristics of an individual bibliographic entry
It no longer contains the bibliographic data but instead holds a key to the
bibliographic data stored in the bibliographic data file. 

Note: the constant type formattedText used below is used to indicate a new field type to support formatted text. A possible solution is "to add a new object that is similar to bookmarks (com.sun.star.text.Bookmark). This extended bookmark would also carry a DOM tree property. See details .

Constants - Type, name, description

string Key

This field contains a key which acts as an index to the bibliographic data stored in the biblio-data.xml file in the save package. The key is defined in the XML like this-

 <cite:biblioref cite:key="urn:isbn:0814712827#154"> 

formattedText CitationString

The formatted citation text, generated by CiteProc, to be displayed in the document. This contains a copy of the formattedText CitationStringInitial or CitationStringSubsequent depending upon the value of boolean IsInitial.

formattedText CitationStringInitial

The formatted initial citation text, generated by CiteProc, to be displayed.

formattedText CitationStringSubsequent.

The formatted initial citation text, generated by CiteProc, to be displayed.

formattedText CitationPrefix

The formatted text which the user considers citation prefix.( description)

formattedText CitationSuffix

The formatted text which the user considers citation suffix.( description)

formattedText CitationLocation

The formatted text which contains the location details (i.e. page number(s))

string LocationType

The type of location page, chapter, track number (on a CD) etc.

string Location

The number, name, description etc. of the location of the citation.

boolean IsInitial

Determines whether this citation is the first reference (ie first use of the hash key in the text) to the reference within the defined text range. Method: The current API of the Writer provides an interface XTextRangeCompare. With this interface two text ranges (citations are also text ranges) can be sorted. This interface is implemented at each text part (body text, header, footer, footnote areas, text frames, table cells, draw text).

formattedText IbidText

The formatted text generated by CiteProc, usually "Ibid" in English but may be different depending upon the language and style selected.

formattedText IbidTextLocation

The formatted text generated by CiteProc, in the style of "Ibid, pp xx-yy" in English but may be different depending upon the language and style selected.

boolean IsIbid

Determines whether this citation directly follows a citation to the same reference. (ie the the cite:key as the previous citation) so that the IbidText is displayed - a citation like 'Ibid, p 34.'

boolean IsIbidSameLocation

Determines whether this citation directly follows a citation to the same reference and location. (ie the same cite:key and the same location as the previous citation)so that the IbidTextLocation is displayed - a citation like "Ibid, pp xx-yy".

string CitationAuthorName

The author name of the citation

string CitationDate

The date of the citation

booleen ExcludeAuthorName

Determines whether this citation excludes the author name. This option is needed when you have referred to the author's name in the text and do not want it included in the citation. i.e.

Gao Xingjian in his novel 'sole mountain' (1990) explores identity 
and myth in China.

booleen ExcludeDate

Determines whether this citation excludes the date. This option is needed when you have referred to the date in the text and do not want it included in the citation. i.e.

The 1990 novel 'sole mountain' (GaoXingjian) explores identity and 
myth in China.

BibliographyDataField

http://api.openoffice.org/docs/common/ref/com/sun/star/text/BibliographyDataField.html#

Description

These values define parts of bibliographic data. They are used to create a
bibliography in a text document. Depending on the type of the data some of the
fields will usually be left empty.

No longer required as it is redundant with the Citeproc formatting engine.

service Bibliography

com :: sun :: star :: text :: FieldMaster ::

Description

specifies service of a Bibliography field master. See also

com::sun::star::text::TextField

This service needs to be totally rewritten. The current method for generating the bibliography reference list (Bibliography table) uses the standard OpenOffice.org indexing method. The one used for table of contents etc. The new service Bibliography field master will collect the list of citation keys in the document (according to the selected text range) and pass them to the Citeproc formatting engine which will return the formatted Bibliography text to be inserted in the document.

None of the current list of constants for this service needs to be kept as Citeproc does not (at this stage) need any options passed to it. The current constants are:

• boolean IsNumberEntries
• string BracketBefore
• string BracketAfter
• sequence< ::com::sun::star::beans::PropertyValues > SortKeys
•  ::com::sun::star::lang::Locale Locale
• string SortAlgorithm

Some new constants will be required:

boolean IsInText

Determines whether the citations are in-text or footnote/endnote citations. It will be a value provided by the CSL style sheet selected by the user to format bibliographic citations and reference list.

boolean CitationIsFootnote

Determines whether the citations are footnote or endnote citations.

string SelectedStyle

The name of the CSL style sheet selected by the user to format bibliographic citations and reference list.

string BibliographyReferenceListRange

The text range for the Reference list - per-chapter or per-document.

boolean ProtectBibliographyFromUserChanges

Determines whether the reference list text is protected or modifiable for user change. (This option is supported by the current Bibliography table mechanism)