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

From Apache OpenOffice Wiki
Jump to: navigation, search
(User selectable footnote and endnote location: added pic link)
m
(28 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
'''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.  
 
'''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.  
  
Note: We have a separate page devoted to the general [[OOoBib_Functional_Requirements | Functional Requirements of the Bibliographic module]]
+
Note: We have a separate page devoted to the general [[Bibliographic/OOoBib Functional Requirements | Functional Requirements of the Bibliographic module]]
  
 
Please feel free to add, correct or improve this document.'''
 
Please feel free to add, correct or improve this document.'''
 
[[Bibliographic_Project | Back to Bibliographic Index]]
 
  
 
==Introduction==
 
==Introduction==
Line 23: Line 21:
  
 
===Changes to Writer XML file format===
 
===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_Project's_Developer_Page | Bibliographic Developer's page]] for more details.
+
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_Page | Bibliographic Developer's page]] for more details.
  
 
===The Document Style package contents===
 
===The Document Style package contents===
Line 74: Line 72:
 
http://bibliographic.openoffice.org/citation-prefix.png
 
http://bibliographic.openoffice.org/citation-prefix.png
  
===Backwards and Forwards Compatibility===
 
'''Note:''' The question of Backwards and Forwards Compatibility has been discussed on the dev@openoffice.org list. One view is that it may not be required. So this is a matter that needs to be resolved. [[User:Dnw|David Wilson]]'s original idea is presented below.
 
  
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.x and 2.1, 2.2) 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 [http://bibliographic.openoffice.org/backwards.png 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.
 
  
 
==Enhanced Document Style Support==
 
==Enhanced Document Style Support==
Line 142: Line 135:
 
===Enhanced Bookmark Function to Include Formatted Text===
 
===Enhanced Bookmark Function to Include Formatted Text===
  
Some data fields in the bibliography need to support formatted text. For example some scientific document titles need to be able to display words in Italics. Mathematical titles need to represent equations.  
+
Some data fields in the bibliography need to support formatted text. For example some scientific document titles need to be able to display words in Italics. Mathematical titles need to represent equations.
 
+
In discussing how to achieve this, [mailto:Oliver.Specht@sun.com Oliver Specht], has advised that the best approach was to enhance the bookmark object.
+
'''Current situation''' [[User:Dnw|David Wilson]] 22:58, 3 November 2008 (CET)
  
A possible solution is "to add a new object that is similar to bookmarks ([http://api.openoffice.org/docs/common/ref/com/sun/star/text/Bookmark.html com.sun.star.text.Bookmark]). This extended bookmark would also carry a DOM tree property. This 'bookmark' can span over formatted text longer than a paragraph. The user can modify the text inside of this bookmark easily.
+
The RDF repository is implemented and works, the API to work with meta data is defined. We also have code in our ODF import/export filters that is able to import and export meta data at any object implementing the API. The API is implemented for paragraphs only until now as for all other text objects we needed a new bookmark implementation that was finished just last week. Here we have refactored our bookmark code in Writer to support different kinds of bookmarks, one being bookmarks with meta data(*), another one the new field bookmarks (see below).
  
An interface to access the new elements needs to be implemented (sorted by document position).
+
(*)Remark: we decided to implement "text meta", "text meta field" and "meta bookmark start/end" internally as bookmark pairs, though in the API only the latter would appear as such.
 
+
The DOM interfaces are in com.sun.star.xml.dom. (e.g. [http://api.openoffice.org/docs/common/ref/com/sun/star/xml/dom/XDocument.html XDocument.idl], [http://api.openoffice.org/docs/common/ref/com/sun/star/xml/dom/XNode.html XNode.idl], [http://api.openoffice.org/docs/common/ref/com/sun/star/xml/dom/XElement.html XElement.idl])
+
 
+
There's also a service [http://api.openoffice.org/docs/common/ref/com/sun/star/xml/dom/DocumentBuilder.html com.sun.star.xml.dom.DocumentBuilder] available that supports the creation of DOM trees.
+
 
+
The bibliography component works on the DOM tree and can manipulate it independently. In case of using a field the component has to set the resulting string representation of the reference at this field." See [http://qa.openoffice.org/issues/show_bug.cgi?id=66979 issue 66979]
+
  
 
===User selectable footnote and endnote location===
 
===User selectable footnote and endnote location===
There needs to be an option to place the document-wide [http://api.openoffice.org/docs/common/ref/com/sun/star/text/Footnote.html footnotes] and [http://api.openoffice.org/docs/common/ref/com/sun/star/text/Endnote.html endnotes] at a user selectable locations. The reason this needs to be made more flexible is that style manuals specify different locations for footnotes and endnotes, not always at the very end of a document. For example the formatting guidelines for APA and Chicago style submissions specify the following order for the sections in a document:
+
There needs to be an option to place the document-wide [http://api.openoffice.org/docs/common/ref/com/sun/star/text/Footnote.html footnotes] and [http://api.openoffice.org/docs/common/ref/com/sun/star/text/Endnote.html endnotes] at a user selectable locations. Many users require, and style manuals specify, different locations for footnotes and endnotes, not always at the very end of a document. For example the formatting guidelines for APA and Chicago style submissions specify the following order for the sections in a document:
 
<pre>
 
<pre>
 
APA Style  
 
APA Style  
Line 178: Line 165:
 
   Index  
 
   Index  
 
   Colophon </pre>
 
   Colophon </pre>
 +
'''Openoffice.org Writer can not produce a document in the APA or Chicago styles because the Endnotes and Footnotes cannot be placed before tables or an index.'''
  
 +
An other problem with the current Footnote Endnote implementation is that when they are placed at the very end of the document they start on a new page and the user can not add a chapter heading or notes to the state of the footnotes.
 +
The only way a user can have Chapter headings like:
 +
 +
Chapter 27 Endnotes
 +
1. ......
 +
2. ........
 +
 +
is by putting the Chapter Heading in the Header or on the preceding Page, with the rest of the page blank !
 +
[[Image:navigator_footnotes.jpg |frame|Navigator panel showing user-definable Footnote and Endnote Sections]]
 +
It should be possible to use the Navigator to position all the document elements: title page, abstract,references, appendixes,  footnotes/endnotes, tables, figure captions, figures, Glossary, Bibliography, Index, Colophon using the Navigator. The Enhancements suggested here would enable would enable the user to create sections called Footnotes and Endnotes. And the Navigator used to order them. The Proposals here would allow the user to define Footnote and Endnote sections which is not possible now.
 +
 +
====Current Placement Options====
 
The available settings in Writer are as follows: For [http://api.openoffice.org/docs/common/ref/com/sun/star/text/EndnoteSettings.html Endnotes] there is an option in
 
The available settings in Writer are as follows: For [http://api.openoffice.org/docs/common/ref/com/sun/star/text/EndnoteSettings.html Endnotes] there is an option in
 
*Insert-->Section:TAB=Endnote-->[ ] 'Collect at end of section'.  [http://wiki.services.openoffice.org/mwiki/images/d/d5/InsertSectionFootnote.jpg pic]
 
*Insert-->Section:TAB=Endnote-->[ ] 'Collect at end of section'.  [http://wiki.services.openoffice.org/mwiki/images/d/d5/InsertSectionFootnote.jpg pic]
 
If this option is not selected then the default is 'Collect at end of document'.
 
If this option is not selected then the default is 'Collect at end of document'.
 +
 
For footnotes there is an option in
 
For footnotes there is an option in
 
   
 
   
 
*Insert-->Section:TAB=Endnote-->[ ] 'Collect at end of Text'  
 
*Insert-->Section:TAB=Endnote-->[ ] 'Collect at end of Text'  
If this is option not selected then the default is 'Collect at of bottom of Page'.
+
If this option is not selected then the default location of the footnotes is 'Collect at of bottom of Page'.
  
The Options in Tools-->Footnote-->TAB='Footnotes-->Position=[  ] are 'End of Page' or 'End Of Document'. [http://wiki.services.openoffice.org/mwiki/images/b/b5/ToolsFootnoteFootnote.jpg pic]
+
The options in  
 +
* Tools-->Footnote-->TAB='Footnotes-->Position=[  ] are 'End of Page' or 'End Of Document'. [http://wiki.services.openoffice.org/mwiki/images/b/b5/ToolsFootnoteFootnote.jpg pic]
  
There is no Tools-->Footnote-->TAB='Endnotes-->Position=[  ] option, as it is always set to 'Collect at end of Document'. [http://wiki.services.openoffice.org/mwiki/images/9/9b/ToolsFootnoteEndnotes.jpg pic]
+
There is no  
 +
*Tools-->Footnote-->TAB='Endnotes-->Position=[  ]  
 +
option, as it is always set to 'Collect at end of Document'. [http://wiki.services.openoffice.org/mwiki/images/9/9b/ToolsFootnoteEndnotes.jpg pic]
  
Now as we have seen above there is need for the user be able to select the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/FootnoteSettings.html Footnotes]/[http://api.openoffice.org/docs/common/ref/com/sun/star/text/EndnoteSettings.html Endnotes] location so that other document parts such as the index can be inserted after the Footnotes/Endnotes. To achieve this I suggest that an addition option needs to be provided for  
+
====Proposed New Placement Options====
*Tools-->Footnote-->TAB='Footnotes-->'Position='''User Selected Section''' to be added to the 'End of page' and 'End of Document' options.
+
Now, as we have seen above, there is a need for the user be able to select the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/FootnoteSettings.html Footnotes]/[http://api.openoffice.org/docs/common/ref/com/sun/star/text/EndnoteSettings.html Endnotes] location so that other document parts such as an index can be inserted after the Footnotes/Endnotes. To achieve this I suggest that an additional option needs to be provided for the panel item
Also a new option for
+
[[Image:new_toolsFootnoteFootnote.jpg|right|frame|panel showing tools Footnotes/Endnotes new options|panel showing tools Footnotes new options]]
*Tools-->Footnote-->TAB='Endnotes-->'Position='''User Selected Section''' to be added to the 'End of page' and 'End of Document' options, to allow a user to select the section in which the Footnote and Endnote would be located. The default for these options would be the last section of the document.
+
*Tools-->Footnote-->TAB='Footnotes-->'Position='''User Selected Section'''  
 +
to be added to the current 'End of page' and 'End of Document' options.  
  
To support Position='User Selected Section', new options would be added to the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/TextSection.html section options] in Inser->Sections->Tab=Footnotes/Endnotes [http://wiki.services.openoffice.org/mwiki/images/3/3b/InsertSectionFootnotesEndnotes.jpg pic]. The new options would be check boxes with -
+
Also a similar new option for the panel item
 +
*Tools-->Footnote-->TAB='Endnotes-->'Position='''End of User Selected Section'''
 +
to be added to the current 'End of page' and 'End of Document' options, to allow a user to select the section in which the Footnotes and Endnotes would be located at the end of. The default for these options would be the last section of the document.
 +
[[Image:New_insertSectionFootnote.png|frame|right|70px|New panel Insert Section Footnote showing new options]]
 +
To support Footnotes/Endnotes Position='End of User Selected Section', new options would be added to the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/TextSection.html section options] in Insert->Sections->Tab=Footnotes/Endnotes. The new options would be check boxes with -
  
 
*[  ] Place Document Endnotes at the end of this section
 
*[  ] Place Document Endnotes at the end of this section
 
*[  ] Place Document Footnotes at the end of this section.
 
*[  ] Place Document Footnotes at the end of this section.
  
Only one section in each document could have each setting. These options would only be selectable (not grayed out) when Footnote or Endnote Position='User Selected Section'.
+
Only one section in each document could have each setting. These options would only be selectable (not grayed out) when Footnote or Endnote Position='End of User Selected Section'.
  
See issue number [http://qa.openoffice.org/issues/show_bug.cgi?id=37679 37679] for details.
+
See issue number [http://qa.openoffice.org/issues/show_bug.cgi?id=37679 37679] for details. Also see the full Specification document [http://bibliographic.openoffice.org/files/documents/124/3748/file_3748.dat?filename=Spec%20User%20selectable%20endnote%20location%2eodt Specification: User Selectable Footnote Endnote Location] with lots of screen pics etc.
  
 
'''Note:''' Whilst Bibliographic citations can be in-text, footnote or endnote types, the user should still be able to use endnotes with footnote citations or use footnotes with endnote citations. To support this mixture 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 - http://bibliographic.openoffice.org/sym1.gif As more symbols are needed they are doubled and trebled - http://bibliographic.openoffice.org/sym2.gif. The counting is reset for each page.
 
'''Note:''' Whilst Bibliographic citations can be in-text, footnote or endnote types, the user should still be able to use endnotes with footnote citations or use footnotes with endnote citations. To support this mixture 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 - http://bibliographic.openoffice.org/sym1.gif As more symbols are needed they are doubled and trebled - http://bibliographic.openoffice.org/sym2.gif. The counting is reset for each page.
  
'''Note:''' Currently you can select to have both footnotes and endnotes placed at the end of the document, although there is would be little sense in doings this. If you select these options, you will have at the end of the document, a new page with footnotes with the default numbering 1,2,3..., followed by a new page with the endnotes with the default numbering i,ii,iii.... at the very end of the document.
+
'''Note:''' Currently you can select to have both footnotes and endnotes placed at the end of the document, although there is would be little sense in doing this. If you select these options, you will have at the end of the document, a new page with footnotes with the default numbering 1,2,3..., followed by a new page with the Endnotes with the default numbering i,ii,iii.... at the very end of the document. It is imposable to add a Chapter Heading or note between the Footnotes and the Endnotes. When following footnotes, there is no way to to Indicate the Start of the Endnotes in the Table of Contents.
  
 
===Endnotes and footnotes enhanced to enable the first note to be un-numbered===
 
===Endnotes and footnotes enhanced to enable the first note to be un-numbered===
Line 229: Line 238:
  
 
===Make the footnote/endnote option persistent for the editing session.===
 
===Make the footnote/endnote option persistent for the editing session.===
 +
[[Image:InsertFootnote.jpg|right|frame|Insert Footnote/Endnote panel]]
 
The Insert>Footnote dialog the Footnote / Endnote option selector is set always to  
 
The Insert>Footnote dialog the Footnote / Endnote option selector is set always to  
 
footnote as the default. However, each document generally has a preferred type and not many  
 
footnote as the default. However, each document generally has a preferred type and not many  
Line 252: Line 262:
  
 
To support to style requirement 'Endnotes be separated by their relevant Chapter Headings'  needs  new options to be available when Footnotes or Endnotes are set to 'End of document'.
 
To support to style requirement 'Endnotes be separated by their relevant Chapter Headings'  needs  new options to be available when Footnotes or Endnotes are set to 'End of document'.
 
 
  [ ] Inset Chapter Headings  at chapter breaks.
 
  [ ] Inset Chapter Headings  at chapter breaks.
 
  Chapter break heading format Options
 
  Chapter break heading format Options
Line 270: Line 279:
  
 
With footnotes Counting "Per Chapter" and  placed at the end of the document, the only way you can find footnote 5 of chapter 10 is to look through all the footnotes and  find where the numbers have been reset to 1 for the 10th time, then find the next number 5.
 
With footnotes Counting "Per Chapter" and  placed at the end of the document, the only way you can find footnote 5 of chapter 10 is to look through all the footnotes and  find where the numbers have been reset to 1 for the 10th time, then find the next number 5.
Clearly a Chapter heading between note 31 and 1, in the above example would help to make it more clear.
+
Clearly a Chapter heading between note 31 and 1, in the above example would help to make it more clear. Like this:
 +
 
 +
30. For example as shown in two recent surveys on the Táin. Tristram “What is
 +
    the Purpose of the Táin Bó Cúalnge?”, 11-21, and Mallory, Aspects of the Táin.
 +
31. James M. Redfield, Nature and Culture in the Iliad: The Tragedy of Hector
 +
    (Chicago: The University of Chicago Press, 1975), 72.
 +
.
 +
'''Chapter 2. Honour, Status and Law'''
 +
.
 +
1. Miller has described this situation in the Icelandic context. There are many
 +
    similarities with early Irish society. William Ian Miller, Bloodtaking and
 +
    Peacemaking: Feud, Law and Society in Saga Iceland (Chicago: The University
 +
    of Chicago Press, 1990
 +
 
 
To support this a new [http://api.openoffice.org/docs/common/ref/com/sun/star/text/textfield/module-ix.html text field] would need to be provided –  
 
To support this a new [http://api.openoffice.org/docs/common/ref/com/sun/star/text/textfield/module-ix.html text field] would need to be provided –  
  
Line 281: Line 303:
 
Also, 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. ([http://qa.openoffice.org/issues/show_bug.cgi?id=50220 Issue 50220]).
 
Also, 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. ([http://qa.openoffice.org/issues/show_bug.cgi?id=50220 Issue 50220]).
  
 +
==== Chapter Names in Indexes====
  
 +
A somewhat related issue is [http://bibliographic.openoffice.org/issues/show_bug.cgi?id=24251 #24252]
 +
 +
"In word chapter numbers appear in the index followed by a '-' separator followed
 +
by the page number. If there is no chapter number the separator '-' is not
 +
shown. In OpenOffice there is no way to replicate this in the filter. If we
 +
create a '-' text token it will appear regardless of whether or not there is a
 +
chapter index. We need some kind of conditional separator in order to support
 +
chapter numbers in indexes." And "... it might be better to support chapter numbers in page number fields."
 +
 +
Currently the index produces results like:
 +
Index
 +
Limerick .................................................................  1
 +
Clare  ...................................................................  5
 +
Kerry ....................................................................  9
 +
Waterford  ............................................................... 19
 +
 +
What is wanted is a index like
 +
 +
Index
 +
Limerick ...................................................... Chapter 1 -  1
 +
Clare  ........................................................ Chapter 1 -  5
 +
Kerry ......................................................... Chapter 2 -  9
 +
Waterford  .................................................... Chapter 3 - 18
  
 
===Insert citation options===
 
===Insert citation options===
Line 339: Line 385:
 
Some document styles such as used in many journals, do not have a new line for each footnote. That is they are all run together as block. As an example the case given above, without new lines.
 
Some document styles such as used in many journals, do not have a new line for each footnote. That is they are all run together as block. As an example the case given above, without new lines.
  
  30. For example as shown in two recent surveys on the Táin. Tristram “What is the Purpose of the Táin Bó
+
-----
Cúalnge?”, 11-21, and Mallory, Aspects of the Táin. 31. James M. Redfield, Nature and Culture in the
+
  30. For example as shown in two recent surveys on the Táin. Tristram “What  
Iliad: The Tragedy of Hector (Chicago: The University of Chicago Press, 1975), 72. 1. Miller has described
+
is the Purpose of the Táin Bó Cúalnge?”, 11-21, and Mallory, Aspects of the
  this situation in the Icelandic context. There are many similarities with early Irish society. William Ian
+
Táin. 31. James M. Redfield, Nature and Culture in the Iliad: The Tragedy of  
Miller, Bloodtaking and Peacemaking: Feud, Law and Society in Saga Iceland (Chicago: The University of
+
Hector (Chicago: The University of Chicago Press, 1975), 72. 1. Miller has  
Chicago Press, 1990).
+
  described this situation in the Icelandic context. There are many similarities  
 +
with early Irish society. William Ian Miller, Bloodtaking and Peacemaking:  
 +
Feud, Law and Society in Saga Iceland (Chicago: The University of Chicago Press,  
 +
1990).
  
Thus an new option is needed to allow users to select 'Footnotes run together'.
+
Thus an new option in [http://api.openoffice.org/docs/common/ref/com/sun/star/text/Footnote.html service Footnote] is needed to allow users to select the new option 'Footnotes run together' in the Tools->Footnote..->Tab=Footnote panel. [http://qa.openoffice.org/issues/show_bug.cgi?id=70579 issue 70579]
  
 
==Other "Nice to Have" Improvements==
 
==Other "Nice to Have" Improvements==
Line 360: Line 409:
  
 
===Bibliographic attributes should be available from the Cross-reference facility===
 
===Bibliographic attributes should be available from the Cross-reference facility===
 +
[[Image:xref.png|frame|right|The cross-reference panel showing bibliographic database fields]]
 
It would be useful if bibliographic references and their data fields were accessible in the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/ReferenceMarks.html Cross-reference] tool.   
 
It would be useful if bibliographic references and their data fields were accessible in the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/ReferenceMarks.html 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).  
+
The proposal is to add document's Bibliographic entries as a new reference type into the Cross-reference 'References' tab. (See the panel on the right.) 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.
 
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.
  
Line 369: Line 419:
 
to build this use this just so we can display the book's Publisher's name in  
 
to build this use this just so we can display the book's Publisher's name in  
 
the text, but we could be dealing with more significant entries such as  
 
the text, but we could be dealing with more significant entries such as  
Abstracts and Notes. T
+
Abstracts and Notes.
 
+
http://www.openoffice.org/nonav/issues/showattachment.cgi/26000/xref.png
+
  
 
===Bibliography Table, make selectable for per-chapter and per-document===
 
===Bibliography Table, make selectable for per-chapter and per-document===
Line 380: Line 428:
 
See [http://qa.openoffice.org/issues/show_bug.cgi?id=49050 issue 49050].
 
See [http://qa.openoffice.org/issues/show_bug.cgi?id=49050 issue 49050].
  
[[Category:Writer issues]] [[Category:Development]] [[Category:Bibliographic]]
+
[[Category:Writer/Effort/Planned]][[Category:Bibliographic]]

Revision as of 11:50, 11 November 2009

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.

Note: We have a separate page devoted to the general Functional Requirements of the Bibliographic module

Please feel free to add, correct or improve this document.

Introduction

Enhancements of the bibliographic facility are considered in four parts-

  • 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 Bibliographic module components.)
  • The enhancements need to the OpenOffice word-processor Writer to support the Citeproc formatting engine.
  • The enhancements needed in Writer to make it a tool suitable for professionals, as well as the rest of us, by better supporting the different types of document and publication styles and layout requirements in common usage. The principle being - if you can see it in a published book or journal, the user should be able to easily set Writer to replicate that format.

This document details the latter two sets of proposed enhancements. The enhancements are shown in rough order of priority.

Changes Needed to Support Citeproc

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.

The Document Style package contents

The Document Style Package could contain the following information-

  • The bibliographic data for each citation referred to in the text, plus any other references the user selected to store in the document.
  • The original data source URL for each reference.
  • The Style full name, and version number.
  • The user selectable style options.
  • Name of macro to set up document formatting options (margins, headings etc.)
  • Rules defining the automated treatment repeating footnote references with 'Ibid' or equivalents.
  • The bibliographic table sorting library name (to select the sorting module).
  • The name of CiteProc program to format to the defined style -
    • In-text citations
    • Footnote initial citations
    • Footnote subsequent citations
    • Endnote initial citations
    • Endnote subsequent citations
    • Bibliographic table entries

The citation field needs to support suffix and prefix text components

In designing the citation API and the citation text-field the handling of other text related to the citation, citation-suffix and citation-prefix, needs to be considered. The importance of this support becomes clear when we consider the handling of converting footnote citations to in-text citations, and vice-versa.

In general any non-bibliographic text would remain in the footnote when the citation was moved to in-text. The Insert->Bibliographic dialog (or another method) would need to allow the user to tag or insert text what was to be a suffix or a prefix to the citation whatever citation method was selected. The prefix and suffix text would always be moved with the citation. If no other text was then left in the footnote, then the footnote would be deleted. For example, a text fragment and the footnote:

Farmers used arable land for grain and stock, and shared major items of equipment
such as ploughs, mills and kilns (for drying grain). The law-tracts describe the
ideal farm as having equal numbers of cattle, sheep and pigs.[9] The prescription 
of equal numbers of farm animals, belies the central importance of cattle in the
Irish economy. 
[9] Economic activity and farming practices are described in Patterson, Cattle
Lords & Clansmen, 62-88. The law tract that provides a description of farming
prerequisites is found in Cra­th Gablach, ed. and trans. D. A. Binchy (Dublin:
Stationary Office, 1941). This topic will be considered in more detailed in
Chapter 5.

The italics text should be regarded as the prefix text to the citation so that if it was converted to in-text style, it would be copied with the citation (as shown below) The text that was not citation or citation prefix or suffix would be left in the footnote after style conversion:

Farmers used arable land for grain and stock, and shared major items of equipment
such as ploughs, mills and kilns (for drying grain). The law-tracts describe the
ideal farm as having equal numbers of cattle, sheep and pigs. Economic activity
and farming practices are described in [Patterson, 1994. 62-88]. The law tract that
provides a description of farming prerequisites is found in [Binchy, 1941].[9]
The prescription of equal numbers of farm animals, belies the central importance
of cattle in the Irish economy. 
[9] This topic will be considered in more detailed in Chapter 5.

As a suggestion, the citation suffix and prefix areas could be shown in Writer as follows: citation-prefix.png


Enhanced Document Style Support

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 Writer and Citeproc need to support-

  • In-text citations (see below)
  • Footnote initial citations (see below)
  • Footnote subsequent citations
  • Endnote initial citations
  • Endnote subsequent citations
  • Ibid text string
  • Bibliography / Reference Table

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 should provide a list of the installed Document Style Packages (see next section). Other options would be to Import and Export for Document Style Packages.

The current facilities support only one default document style. Document style selection should apply to the whole document. Styles such as MLA's 'Research Paper' defines line spacing, margins and headings etc and these settings should be available as part of the style package as well. Also there are options within styles. For example, an other bibliographic software utility provides the following options for style - '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

Some of these setting can be achieved using templates. A Wizard could be written to guide the user through the style options. See issue 4295

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. ibid. page 345.
36. ibid.

See issue 2492

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. Also, for special treatment for repeated, adjacent citations to the same work (ie. requiring ibid.)

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.

Implementation: Code needs to be written to set first and subsequent occurrence flag, and for the 'repeated, adjacent citations' flag for each reference. This code might not need to be built from scratch, as it may be similar in operation to the Writer Cross-Reference facility's Before/After flags for bookmarks.

Enhanced Bookmark Function to Include Formatted Text

Some data fields in the bibliography need to support formatted text. For example some scientific document titles need to be able to display words in Italics. Mathematical titles need to represent equations.

Current situation David Wilson 22:58, 3 November 2008 (CET)

The RDF repository is implemented and works, the API to work with meta data is defined. We also have code in our ODF import/export filters that is able to import and export meta data at any object implementing the API. The API is implemented for paragraphs only until now as for all other text objects we needed a new bookmark implementation that was finished just last week. Here we have refactored our bookmark code in Writer to support different kinds of bookmarks, one being bookmarks with meta data(*), another one the new field bookmarks (see below).

(*)Remark: we decided to implement "text meta", "text meta field" and "meta bookmark start/end" internally as bookmark pairs, though in the API only the latter would appear as such.

User selectable footnote and endnote location

There needs to be an option to place the document-wide footnotes and endnotes at a user selectable locations. Many users require, and style manuals specify, different locations for footnotes and endnotes, not always at the very end of a document. 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 

Openoffice.org Writer can not produce a document in the APA or Chicago styles because the Endnotes and Footnotes cannot be placed before tables or an index.

An other problem with the current Footnote Endnote implementation is that when they are placed at the very end of the document they start on a new page and the user can not add a chapter heading or notes to the state of the footnotes. The only way a user can have Chapter headings like:

Chapter 27 Endnotes 
1. ......
2. ........

is by putting the Chapter Heading in the Header or on the preceding Page, with the rest of the page blank !

Navigator panel showing user-definable Footnote and Endnote Sections

It should be possible to use the Navigator to position all the document elements: title page, abstract,references, appendixes, footnotes/endnotes, tables, figure captions, figures, Glossary, Bibliography, Index, Colophon using the Navigator. The Enhancements suggested here would enable would enable the user to create sections called Footnotes and Endnotes. And the Navigator used to order them. The Proposals here would allow the user to define Footnote and Endnote sections which is not possible now.

Current Placement Options

The available settings in Writer are as follows: For Endnotes there is an option in

  • Insert-->Section:TAB=Endnote-->[ ] 'Collect at end of section'. pic

If this option is not selected then the default is 'Collect at end of document'.

For footnotes there is an option in

  • Insert-->Section:TAB=Endnote-->[ ] 'Collect at end of Text'

If this option is not selected then the default location of the footnotes is 'Collect at of bottom of Page'.

The options in

  • Tools-->Footnote-->TAB='Footnotes-->Position=[ ] are 'End of Page' or 'End Of Document'. pic

There is no

  • Tools-->Footnote-->TAB='Endnotes-->Position=[ ]

option, as it is always set to 'Collect at end of Document'. pic

Proposed New Placement Options

Now, as we have seen above, there is a need for the user be able to select the Footnotes/Endnotes location so that other document parts such as an index can be inserted after the Footnotes/Endnotes. To achieve this I suggest that an additional option needs to be provided for the panel item

panel showing tools Footnotes new options
  • Tools-->Footnote-->TAB='Footnotes-->'Position=User Selected Section

to be added to the current 'End of page' and 'End of Document' options.

Also a similar new option for the panel item

  • Tools-->Footnote-->TAB='Endnotes-->'Position=End of User Selected Section

to be added to the current 'End of page' and 'End of Document' options, to allow a user to select the section in which the Footnotes and Endnotes would be located at the end of. The default for these options would be the last section of the document.

New panel Insert Section Footnote showing new options

To support Footnotes/Endnotes Position='End of User Selected Section', new options would be added to the section options in Insert->Sections->Tab=Footnotes/Endnotes. The new options would be check boxes with -

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

Only one section in each document could have each setting. These options would only be selectable (not grayed out) when Footnote or Endnote Position='End of User Selected Section'.

See issue number 37679 for details. Also see the full Specification document Specification: User Selectable Footnote Endnote Location with lots of screen pics etc.

Note: Whilst Bibliographic citations can be in-text, footnote or endnote types, the user should still be able to use endnotes with footnote citations or use footnotes with endnote citations. To support this mixture 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 - sym1.gif As more symbols are needed they are doubled and trebled - sym2.gif. The counting is reset for each page.

Note: Currently you can select to have both footnotes and endnotes placed at the end of the document, although there is would be little sense in doing this. If you select these options, you will have at the end of the document, a new page with footnotes with the default numbering 1,2,3..., followed by a new page with the Endnotes with the default numbering i,ii,iii.... at the very end of the document. It is imposable to add a Chapter Heading or note between the Footnotes and the Endnotes. When following footnotes, there is no way to to Indicate the Start of the Endnotes in the Table of Contents.

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 Footnotes or Endnotes number series to begin with a zero. Then changing the code to ensure that the number for note zero would be suppressed in the display. That is, allowing users to select

  • Tools-->Footnotes-->TAB={Footnotes or Endnotes}-->Start At='0'

Currently '1' is the minimum number selectable.

Make the footnote/endnote option persistent for the editing session.

Insert Footnote/Endnote panel

The Insert>Footnote dialog the Footnote / Endnote option selector is set always to footnote as the default. However, each document generally has a preferred type and not many documents use both. When one is working on a document with endnote references, it is a pain to have to select endnote option for each reference insertion.

I propose that the Footnote / Endnote Option be made persistent for the session. So that if I select endnote type, this selection will persist for the editing session. See issue 20823

Enhanced Heading Support for Footnotes and Endnotes

The currently the Endnotes (and sometimes Footnotes) are presented as a solid block of notes at the end of the document or chapter. The Chicago Manual of Style, 15th edition, Running heads for notes sections, section 16.60, p 608 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 page header could contain-

Notes to pages 245-268

Two new text fields need to be provided -

notes-start-page and notes-end-page

so the header, with fields showing, would be -

 Notes to pages [notes-start-page ]-[notes-end-page]

To support to style requirement 'Endnotes be separated by their relevant Chapter Headings' needs new options to be available when Footnotes or Endnotes are set to 'End of document'.

[ ] Inset Chapter Headings  at chapter breaks.
Chapter break heading format Options
[ ] Chapter Number  [  ] Numeric] or Alphabetical [ ]  {ie "Chapter 5" or "Chapter Five"}
[ ] chapter number and title.  {ie “Chapter Four: Ronald Reagan's Bitburg Narrative”}

This requirement is particularly apparent when the footnotes have been set with the option Counting "Per Page" or "Per Chapter" when they placed at the end of the document -

30. For example as shown in two recent surveys on the Táin. Tristram “What is 
    the Purpose of the Táin Bó Cúalnge?”, 11-21, and Mallory, Aspects of the Táin.
31. James M. Redfield, Nature and Culture in the Iliad: The Tragedy of Hector
    (Chicago: The University of Chicago Press, 1975), 72.
1. Miller has described this situation in the Icelandic context. There are many
   similarities with early Irish society. William Ian Miller, Bloodtaking and
   Peacemaking: Feud, Law and Society in Saga Iceland (Chicago: The University 
   of Chicago Press, 1990

With footnotes Counting "Per Chapter" and placed at the end of the document, the only way you can find footnote 5 of chapter 10 is to look through all the footnotes and find where the numbers have been reset to 1 for the 10th time, then find the next number 5. Clearly a Chapter heading between note 31 and 1, in the above example would help to make it more clear. Like this:

30. For example as shown in two recent surveys on the Táin. Tristram “What is 
    the Purpose of the Táin Bó Cúalnge?”, 11-21, and Mallory, Aspects of the Táin.
31. James M. Redfield, Nature and Culture in the Iliad: The Tragedy of Hector
    (Chicago: The University of Chicago Press, 1975), 72.
.
Chapter 2. Honour, Status and Law
.
1. Miller has described this situation in the Icelandic context. There are many
   similarities with early Irish society. William Ian Miller, Bloodtaking and
   Peacemaking: Feud, Law and Society in Saga Iceland (Chicago: The University 
   of Chicago Press, 1990

To support this a new text field would need to be provided –

footnotes-chapter-start 

Also the Styles area of the footnote panel would need an additional style for this new heading -

Footnote Break Headings

Also, 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).

Chapter Names in Indexes

A somewhat related issue is #24252

"In word chapter numbers appear in the index followed by a '-' separator followed by the page number. If there is no chapter number the separator '-' is not shown. In OpenOffice there is no way to replicate this in the filter. If we create a '-' text token it will appear regardless of whether or not there is a chapter index. We need some kind of conditional separator in order to support chapter numbers in indexes." And "... it might be better to support chapter numbers in page number fields."

Currently the index produces results like:

Index
Limerick .................................................................  1
Clare  ...................................................................  5
Kerry ....................................................................  9
Waterford  ............................................................... 19

What is wanted is a index like

Index
Limerick ...................................................... Chapter 1 -  1
Clare  ........................................................ Chapter 1 -  5
Kerry ......................................................... Chapter 2 -  9
Waterford  .................................................... Chapter 3 - 18

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.

Footnotes without new lines

Some document styles such as used in many journals, do not have a new line for each footnote. That is they are all run together as block. As an example the case given above, without new lines.

----- 
30. For example as shown in two recent surveys on the Táin. Tristram “What 
is the Purpose of the Táin Bó Cúalnge?”, 11-21, and Mallory, Aspects of the
Táin. 31. James M. Redfield, Nature and Culture in the Iliad: The Tragedy of 
Hector (Chicago: The University of Chicago Press, 1975), 72. 1. Miller has 
described this situation in the Icelandic context. There are many similarities 
with early Irish society. William Ian Miller, Bloodtaking and Peacemaking: 
Feud, Law and Society in Saga Iceland (Chicago: The University of Chicago Press, 
1990).

Thus an new option in service Footnote is needed to allow users to select the new option 'Footnotes run together' in the Tools->Footnote..->Tab=Footnote panel. issue 70579

Other "Nice to Have" Improvements

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 is this 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

Bibliographic attributes should be available from the Cross-reference facility

The cross-reference panel showing bibliographic database fields

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 on the right.) 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.

This would allow the user select any of the bibliographic elements from the bibliographic record and display them in the text. It might seem a bit trivial to build this use this just so we can display the book's Publisher's name in the text, but we could be dealing with more significant entries such as Abstracts and Notes.

Bibliography Table, make selectable for per-chapter and per-document

Most of the Indexes and Tables have an option for them to apply on a per-chapter or on a per-document basis. The Bibliography Table does not. If we work on the principle that OOo Writer should be able to produce what we see in books, and collections of papers or essays do have per-chapter bibliographies then Writer should have this option as well.


See issue 49050.

Personal tools