Bug 68123 - Other: Bibliography examples misleading & hard to use
Summary: Other: Bibliography examples misleading & hard to use
Status: NEW
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Writer (show other bugs)
Version:
(earliest affected)
4.1.1.1 rc
Hardware: Other All
: medium enhancement
Assignee: Not Assigned
URL:
Whiteboard: BSA
Keywords:
Depends on:
Blocks: Bibliography
  Show dependency treegraph
 
Reported: 2013-08-14 22:50 UTC by Bruce Byfield
Modified: 2016-08-02 14:40 UTC (History)
4 users (show)

See Also:
Crash report or crash signature:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Bruce Byfield 2013-08-14 22:50:52 UTC
The Bibliography tool gives misleading examples, making how to use it confusing.

The specific problem is with the "Identifier" field. In the entry form this is called the "Short Name." The first problem is that the field needs to be named consistently.

The second problem is that the example entries for the field are nonsensical. Although you wouldn't know it from the names, the field is actually the form that the citation should take within the text -- for example, (Smith: 1997) in the APA style. The nonsensical examples should be replaced with one that will actually indicate the purpose of the field, such as In-Text Citation.

The same field also needs renaming at Insert ->Indexes and Tables -> Bibliography Entry, where "Short Name" is used

Solving these problems is relatively easy, and would at least indicate how to use the tool.

However, the tool would also benefit from:

1.) The ability to attach a unique bibliography index to each document.

2.) The ability to chose the database for major citation styles (APA, MLA, Chicago). 

3.) Making the type of source (for instance, a book or URL) a mandatory field that determines what information is needed for a complete entry for that type of source. When a bibliography is created with Insert ->Indexes and Tables -> Index and Tables -> Index/Table -> Type, then all the information required for that type of source would be inserted.

Since guides are available for all major citation styles, all these suggestions would be more tedious than difficult. They might make a good project for a mentoring program.
Operating System: All
Version: 4.1.1.1 rc
Comment 1 Thorsten Behrens (CIB) 2013-08-15 15:05:24 UTC
Makes sense to me, and could even qualify as an easy hack - Astron, any input from UX side on the proposal?
Comment 2 Owen Genat (retired) 2014-01-30 09:33:22 UTC
(In reply to comment #0)
> The Bibliography tool gives misleading examples, making how to use it
> confusing.
> 
> The specific problem is with the "Identifier" field. In the entry form this
> is called the "Short Name." The first problem is that the field needs to be
> named consistently.
> 
> The second problem is that the example entries for the field are
> nonsensical. Although you wouldn't know it from the names, the field is
> actually the form that the citation should take within the text -- for
> example, (Smith: 1997) in the APA style. The nonsensical examples should be
> replaced with one that will actually indicate the purpose of the field, such
> as In-Text Citation.

Seems like it would be a good idea to keep the documentation team informed of any changes made in this respect. I do not know what the standard method of doing this is, otherwise I would make the change. Is the Documentation ML added as a CC?

> 2.) The ability to chose the database for major citation styles (APA, MLA,
> Chicago). 

There is a point and screenshot, that seems related to this exact issue, noted for the FOSEM 2014 UX hackfest: https://wiki.documentfoundation.org/Hackfest/FOSDEM2014#Ideas Thanks are due to Fabian for pointing this out in bug 73275.
Comment 3 Stefan Knorr (astron) 2014-02-01 16:42:03 UTC
Hi all,

so, I have never used that part of LibreOffice(I should have, I guess).

Given all the information that LibreOffice already has from the bibliography database, shouldn't it be able to create the short names itself, given enough hints on what to create them from? (The hints on the format could be something like (%author %year: %page), or to make it a little nicer there could be UI to drag-and-drop predefined fields into a text field.)
If we had that, the short name/identifier field wouldn't actually need to exist.

then,
1. sounds good.
2. I am not sure I understand -- do you mean a web database?
3. right.
Comment 4 Owen Genat (retired) 2014-02-03 10:20:45 UTC
(In reply to comment #3)
> Given all the information that LibreOffice already has from the bibliography
> database, shouldn't it be able to create the short names itself, given
> enough hints on what to create them from? (The hints on the format could be
> something like (%author %year: %page), or to make it a little nicer there
> could be UI to drag-and-drop predefined fields into a text field.)
> If we had that, the short name/identifier field wouldn't actually need to
> exist.

In simple terms, yes. In reality it is more complex. I agree that the basic citation form (short name) should be dispensed with in favour of a simple unique identifier, such as an incrementing integer.

The short name field is (currently) the form of the in-text citation. Citation form is set according to a predefined style (e.g., APA, Chicago, Turabian, Vancouver, etc.) as indicated in (2) in the description. The form for each citation is then dependent on various subsidiary factors (according to style manual), such as: (a) the title/date fields being populated; (b) whether the citation is the first or subsequent in the text; (c) the number of authors; just to name a few. The initial implementation would probably need to be a fairly simple improvement (as you suggest) rather than going to this level of support.

> 2. I am not sure I understand -- do you mean a web database?

This is the example I was referring to: http://gcflearnfree.files.wordpress.com/2013/11/style.png?w=610
Comment 5 Stefan Knorr (astron) 2014-02-03 15:59:56 UTC
(In reply to comment #4)
> In simple terms, yes. In reality it is more complex. I agree that the basic
> citation form (short name) should be dispensed with in favour of a simple
> unique identifier, such as an incrementing integer.

That was not really what I meant. :) I thought that the short name could already reflect the citation style -- there is absolutely no need to expose a running number in the UI. So, if the short name is only used for a running number... we don't want the user to ever see it.

What I was proposing was to have some sort of pattern language that would automatically create references in the correct style as the short name. I.e. you would set the correct format once for the in-text citations and once for the citations page and LibreOffice would mangle your data to do the right thing.


> > 2. I am not sure I understand -- do you mean a web database?
> 
> This is the example I was referring to:
> http://gcflearnfree.files.wordpress.com/2013/11/style.png?w=610

That does not help me. I don't know this Word feature.
Comment 6 Owen Genat (retired) 2014-02-07 14:28:17 UTC
(In reply to comment #5)
> That was not really what I meant. :) I thought that the short name could
> already reflect the citation style -- there is absolutely no need to expose
> a running number in the UI. So, if the short name is only used for a running
> number... we don't want the user to ever see it.

I would not want to see an integer identifier exposed to the user either. Rather I was thinking of making the "Identifier" database field, exactly that, an integer identifier and hiding it from the user. As Bruce indicated, labelling this field as "Short Name" on the form is unhelpful. The purpose of this field appears to be that of a primary key associating the in-text citation with the bibliography index entry. This works fine for sequence-type citation systems (e.g., Vancouver), but is no good for author-date systems (e.g., APA, Chicago), where the in-text citation needs to be "(Author, 1987)". This citation information cannot (and should not) be used in the index. Sorry I wasn't clear about this.

> What I was proposing was to have some sort of pattern language that would
> automatically create references in the correct style as the short name. I.e.
> you would set the correct format once for the in-text citations and once for
> the citations page and LibreOffice would mangle your data to do the right
> thing.

Overall, I think we are in agreement. It really just comes down to how: 

(a) the citation format and bibliography (index) entry format is calculated;
(b) performance issues with doing this calculation, as it is not stored information.

The main concern I would have is performance in relation to a large bibliography, for example changing all reference-related entries from APA to Vancouver style. Each and every citation and bibliography entry needs to be redone. I imagine Word does it though, so it is likely possible.

> That does not help me. I don't know this Word feature.

It is just a pull down list to select the style manual (APA, Chicago, etc.) to be used in calculating the format for the citations and bibliography entries. This is the main determining factor of how both in-text citations and bibliography entries appear and equates to your statement of "you would set the correct format". Note however that there is only /one/ format, not one for the citations and one for the bibliography. This is the big red switch, so to speak.
Comment 7 Alex Thurgood 2015-01-03 17:40:42 UTC Comment hidden (no-value)