Writers Guide: Bibliography section partial review

English
#1

LibreOffice 7.5.1.2
Win11-64
WG75-Writers Guide
GS74-Getting Started

This is not a criticism. You have a great product and I enjoy using it. It is an analysis of faults, a critique, meant to (at least) state what is confusing to me. I am just beginning to use the LibreOffice bibliography and have thought to read the documentation before I use the facility. These are some of the things that I have found.

The WG75-Writers Guide Bibliography section needs a review. I think that it contains legacy items no longer used, it contains page numbers which are inaccurate, cyclic references to GS74-Getting Started, contradictory descriptions (of the identifier field), figures which don’t match the text and other things.

As in all reviews, take this one with a grain of salt and aspiration level laughter.

Some issues:
[1] This is the primary source for the Writer application. The “Getting Started Guide” is not the primary source for any application, it is only an aid. Either rename “Getting Started” or ensure that all primary source documents are standalone and need not reference Getting Started. If you elect to continue using the Getting Started Guide as is, then references to this Guide should be direct references to a section in the Guide rather than to the Guide itself. The normal inference on a reference to the Guide is to look for the current topic, in this case Bibliographies. There is not much content from pg. 87, Creating Bibliographies and Indexes, in the Getting Started Guide to the end. If more than an overview is required then address the needed section(s) directly.

[2] Reference to the bibliography section of the Getting Started Guide are cyclic and non-informative. the Writer Guide references the Getting Started Guide which references the Writer Guide for bibliographic information.

[3] A brief referential section seems needed to identify and name, for this document, various items to be covered. Amongst the terms that should be clearly defined are:
a. references: particularly if this means Insert->Field->More Fields items.
b. citation.
c. citation record.
d. citation format.
e. citation style.
5. bibliographic database containing citation record.
g. global bibliographic database.
h. local bibliographic database.
i. embedded bibliographic database.

[5] Some information which needs addressing concerning citations, citation records, and the bibliographic database:
a. What happens when the original file is renamed, moved to the same filesystems, moved between computers.
a. What happens when the file is output in another format (docx, pdf, epub, text, …)
a. What are the issues with embedded, local, global bibliographic databases and renaming, moving.

[6] The Identifier/Short Name field has conflicting definitions.
a. pg. 355 Citations, eg, APA, MLA. Chicago, etc, use the Identifier field.
b. pg. 356 Replace sample entries with the proper citation style format.
c. pg. 357 Enter an entry name in the Short Name box. Should be unique.
d. pg. 357 Enter [Author, date].
e. pg. 360 Select a (ed. unique) reference from the Short Name drop-down
f. pg. 360 Type a unique name.
g. pg. 361 Use the text recorded in the Short Name field.

The conflicts are in the uniqueness requirement and a., b., d. in that uniqueness is not guaranteed, and in the usage in a., b. and for example, c. and d..

[7] I suspect the pg. 355 Citation Style section is a legacy item and should be removed. If it is not then some or all of the following apply:
a. The conflict in use of the Short Name Field has been noted.
b. What each style looks like is nowhere supplied.
c. External references defining the styles are not supplied.
d. External references to get additional styles other than the 4 main styles is not supplied.
e. What ASCII text is to be used for these and other citation styles in the Short Name Field.

[8] The word ‘Citation’ is used in multiple contexts. As a ‘citation’ style, a bibliographic entry in the database, a reference to a bibliographic entry in the document, and a bibliography entry in the document. This is confusing.

[9] Nowhere are the database fields, except the Identifier field, defined.
a. The Type field and its relationship to pg. 362 Figure 369 is undefined.
b. The relationship between fields and Type format is undefined. Which fields are needed for which output forms.
c. Conflicts in Identifier formats are unresolved, eg, an author creates multiple entries on the same day or in the same year, this makes the Identifier non-unique which is allowed. How is a reference to one of this non-unique names made.
d. How are multiple editors, authors entered.
e. What is the difference between and organization and an institution.
f. and so on.

[10] Which documents can have a bibliographic database, writer, calc, impress, …, and how are the references represented. Other documents should be cited, and this information should be put into the Getting Started Guide.

[11] pg. 355 Tip.
a. “Writer has a single bibliography database for all documents”, this is clearly inaccurate.
b. Provide a reference to the relevant template information. If in-document, then link to it. The Getting Started Guide provides for Creating index and bibliographies provides no useful information.

[12] Note:
a. Nowhere are the citation record fields related to a citation format/style.
b. Clarification between ‘citation format’ and ‘citation style’ seems warranted.
c. Change “single entry” to “citation record”. Note that multiple names are used for the same thing.

[13] Caution. The Short Name Field usage needs further definition.

[14] “Changing the data source” The concept “Data Source” is undefined. The use of a Data Source depends on the definition of a local bibliographic database which is also undefined. The distinction between a data source which is a global bibliographic database is also undefined. The definition of “global” in the context of a Writer is also undefined. At this point, “Changing the data source” has no meaning.
a. What is unaddressed is that when the data source is changed, it is changed for this instance of the LibreOffice application. If several documents are open, each with a different local bibliographic database, then all but one will have a valid bibliographic database, the rest will have an invalid data source, i.e., the one that has been changed. If this statement is accurate then this is a flaw in LibreOffice. It does not allow several articles to be open, each with its own data source, to be changed in parallel. Instead, each time the subject of the changes are shifted, the data source needs to be changed.
b. It might be more appropriate to say “Changing the bibliographic database”.
c. What happens to the global example data source if a new version of LO is used. What happens to any changes made?

[15] “Filtering records” No rationale is given as to why this is needed or desired. What is the object of record filtration?
a. The legends in the form are undefined.
b. The fields are undefined.
c. The processing algorithm is undefined.
d. Missing is ctrl-shift-F4->{auto filter, apply filter, standard filter, reset filter}
e. Missing is Tool->Bibliographic database->{auto filter, standard filter}

[16] “Adding entries to the database”
a. 1) change “records” to “citation records”.
b. 2) Note that ctrl-shift-F4->Edit Data adds a citation record which can be edited if and only if its predecessor record has an entry.
c. 3) “Enter name”, note previously identified duplicate meanings. Note also that some meanings preclude the entry from being unique. Note that there is no identified way to create citation references with duplicate citation record names.

[17] “Maintaining entries in the database”
a. “entries” should be changed to “citation records”
b. ctrl-shift-F4 allows citation record modification.

[18] “Column details”
a. A “column” has not been described. The distinction is important. There are more database types than Codd Relations, and in most a column has no meaning. It might be better to define a citation record independently before this point, and to relate the citation record fields to the UI legends and field contents, to the database presentation format in Tools->Bibliographic database or ctl-shift-F4. Then to state that the presentation format for citation records in the bibliographic database looks like a spreadsheet, and that each citation record field is a column in this presentation. The document did say that the bibliographic database looked like a spreadsheet but a little more wordage may be in order. Note that showing the UI and not stating the direct relationship to a citation record is deceptive, as well as the citation record ‘column’ names are not the same as in the UI, for example, 'University" is a ‘School’.
b. Figure 361 and Figure 363 are both missing “Local Copy”, and that “Local Copy” is not in the citation record and as a result, there is an error each time Tools->Bibliography Database is used.
c. The UI in Figure 361 and 363 are different. Does that difference in content warrant a discussion?

[19] “Field details” you are depending on your reader to understand what a ‘field’ is.
a. ‘level’: You probably mean to say something line the sidebar on the left shows hierarchical trees, one for each registered citation database. Select the database being used and click on each level to get to the citation record entry, that is ->Tables->, then left click on . In our example this is Bibliography->Tables->biblio. Otherwise, "level’ has no meaning.
b. 3) or 5) Right-click the citation record entry (ed. or select the column/field) …
c. 5) in my version of LO I get Figure 365 not Figure 366.
d. 5) Where is anything in Figure 366 defined?
e. 6) where is the “Field Type” anything?

[20] Figure 361 UI looks better than the flat field look in LibreOffice.

I’m sorry. I just ran out of time. The document needs some clarification and a critical review. Most particularly, some attention to defining things and using consistent names throughout the document.

1 Like
#2

Would have been better to post this to https://community.documentfoundation.org/ Documentation - LibreOffice guides category.

#3

Note that we are users just like you. Indeed, suggestions for the documentation should be directed elsewhere. More ideally, you could contribute directly to improving that section of the documentation.

On another note, be aware that the bibliography feature in Writer is very basic, and quickly will not fulfill more advanced needs. If it becomes limiting for you, I suggest considering the open source software Zotero for bibliography management and referencing. It has plugins for citing and generating bibliographies right in Libre Office.

#4

But be careful with third party bibliography add-on because they mess up your formatting. They are “portable” across suites and consequently are “formatting-agnostic” and implement it their own way with direct formatting which defeats your own styling. They also frequently have additional features such as citations management which goes far beyond merely inserting a bibliography table in a document.
So you have to balance between “polished” fully-controlled formatting and sophisticated citation management.

My recommendation is to use built-in bibliography though basic it is to better define your need. Once you really bump into a limitation, see if opting for an add-on is really worth it against the loss in formatting control. As always, your mileage may vary.

#5

Thanks. Just reposted.

#6

Thanks for noting that it should be reposted. Done as part of previous message/

The critique provided is of the text in the Writer’s Guide. It does not address any additional request functionality. The existing Bibliography description may need some change, depending on how relevant the comments are. There are things in the existing document that are not mentioned, things which appear to be relics from some previous LO implementation. inconsistency in names, contradictions in field usage, and etc. This is a partial note on the first 5 pages on the text.

#7

@ajlittoz My intent is to use LO bibliography. I don’t see any need to consider any alternative.

The comments are not on adding new functionality but on reviewing the existing documentation.

As to “polished”, I think the existing stuff is good. In time I would expect it to become “gooder”.

#8

@Vanadium In the past on other (usually) Free Software Foundation (FSF) products I have provided chapters for inclusion in manuals and software. I have found that in general, the FSF personnel are ego involved in their products. That is, they have labored long and hard to produce something that they are proud of (and should be), and take any outside change as an affront. My view on things that I do are that my eyes are only two. Any outside eyes (and comments) are more than welcome, they are desired. My hesitation is then that spending long hours in providing a document which (I feel) is suitable is wasted time if it is discarded. So, I am hesitant to spend more time. And, I would have to be integrated into the development team, both to provide input in direction and to discover what has been done. And that is another issue, I have never used this product and my issues are consequent. So what happens if I am a contributor and integrated. I comment. The comments are rejected. My time is wasted.

2 Likes
#9

Of course, you have your experience, but free software projects usually can use contributions to documentation - software developpers do not necessarily like to also write a manual.

The only point we are trying to make here is that this site is populated by users, like you and myself. Thus, your question may be read with interest here, but cannot be answered here. At best, someone reads along that is already involved in the LO documentation and picks it up.

#10

I have attempted to contribute documentation. The effort failed after I indicted that the existing description format needed to be changed, it wasn’t suitable for describing the Bibliography process successfully. So although I am willing, LibreOffice is not.

#11

The existing implementation of the Bibliography Database is severely flawed. Multiple bugs, including the failure of styling, the inability to copy, the inability to change content, and etc. After 4-5 weeks on a two day job I am going to zotero. If it provides any format then that would be better than the existing implementation.

#12

Beware! Zotero is yet another product, independent from Writer and has a much wider scope than just Bibliography quoting. Being application-agnostic, it does not integrate natively with any office suite. Because of its “agnosticity”, it reimplements many formatting features through macros and this is the beginning of the problems. As long as you’re happy with Zotero “artistic” choices, you’re OK. If you want to modify its build-in formatting, you’re out of luck. Any change you apply will not survive further macro triggering.

#13

This issue is that LO is very buggy and is an unsuitable framework for bibliographies. I need a reliable, bug free, platform. Here is a partial listing of failures (from memory):
1: LO rewrites the database. In some modes, LO changes the author fields.
2: LO removes the Short Name from the input form field.
3: LO migrates the Identifier field from one record to another during data entry.
4: Clicking on a citation reference replaces the Short Name field with the authors. I believe it also rewrites the Database Identifier field in this mode, but although LO does it, I’m not sure this is the setup for the condition.
5: Editing the entry style does not work change the appearance for Journal bibliographic entries on update.
6: An update does not output the ‘page(s)’ field or the ‘Volume’ field.
7: I was unable to copy my file and see the bibliography (Win 10-x64 LO 7.5.3.2). Could not Tools->Update the bibliography. Checked that the data source was correct.
8: At one point on data entry, LO moved data base field values from one record to another.
9: Changes to the database were not reflected in an update. The changes had to be made manually.
10: I was unable to create my own database (and there are no instructions on how to do this).
11: As a nit, no list in any Bibliographic function is sorted. That include the database entry form (Type field) and the style function.
12: Clicking on the citation reference shows the author(s) field of the database as the Short Name, not the Identifier field.

I was able to ‘get it working’ by changing the entries manually. Having LO change the database on its own is decidedly bad. The listing of faults detected are only those I remember, not all that occurred. This is a two day job which took upwards of 4 weeks. In addition, the Database lacks integrity because LO apparently did unanticipated changes to it.

#14

Mmmh; that’s a lot.
However, I don’t think LO “changes the database” on its own. I agree Bibliography is quite problematic and documentation is not sufficient. But it is a DB and reliable as a DB. The complication is the integrity of the document. What you have in there is a snapshot of the DB and document must remain the same, whatever happens to the DB after you close the document. The difficulty is to understand this 2-layer approach and how to interact with it.

The simplest case is preparation of the DB ahead of document writing and not changing the DB.

The difficult case is simultaneous elaboration of DB and document. If you change/add entries not yet in the document, you’re roughly in the preceding case. Updating already used entries must be done differently, i.e. not with “ordinary” DB tools but by double-clicking on an inserted entry and editing it from there.

Creating a separate database: must be done before invoking Edit>Exchange Database (or Data Source in the bibliography window), e.g. by copying the default bibliography DB to some user directory. You can then empty the copy and be sure it has the expected structure.

Sorting entries: I assume you’re talking about the list shown by Tools>Bibliography Database. There appears there is no way to do this. The only surrogate is to use a filter but it will not sort anyway.

If you have specific concerns, don’t hesitate to ask targeted questions. Try to avoid multiple issues in posts.

1 Like
#15

@ajlittoz
I am willing to share my document, database and etc. with you on a private channel.

Although your points are well taken, the issues set forth above are all accurate. A new one noticed in the past and rediscovered today is that a second reference to a DB item cause a new reference, i.e., a new number (in my case) and a new entry in the Bibliographic table with the same data as the original.

As to LO modification of the DB. I stand by this. LO does this.

As to multiple issues in the same topic. This is unfortunate, but it takes me an hour or two per topic to correctly identify the issue, identify the steps to duplicate the issue,i illustrate the expected result, and decide whether the issue is a question of enhancement or a bug. Looking at the issues so far identified that turns out to be more than 20hrs. I don’t have time for this, and although you are skeptical nonetheless the rendition is accurate.

If you would like to continue this discussion and resolve the issues then I am open to it. All materials required for you to independently verify my issues can be made available to you on a private channel. If not interested then I understand.

#16

To open a private channel, click ont the icon aside my alias. You get a popup with a Message button.

#17

Does Writer built-in bibliography functionality offer same level of productivity as Zotero on:

  • creating new entries in DB?
  • maintenance of DB entries?
  • browsing DB entries
  • adding source text full-text to matching DB entry?
  • attaching attachments to entries?
  • using web browser to create DB entries?
  • capturing snapshot of web-page closely related to given DB entry and attaching snapshot to DB entry?
  • interoperability with 3rd-party apps using numerous import/export formats?

By the way: Bruce Byfield and Jean Hollis Weber recommend Zotero in their Designing with LibreOffice, 2nd Edition book: “In the first edition of Designing with LibreOffice, I detailed how to work with TOOLS > BIBLIOGRAPHICAL DATABASE. I did so because I wanted to show how to use LibreOffice without extensions. However I now consider that a waste of effort. Instead, I recommend installing…” Recommendation argumentation is provided in same chapter. Book chapter 11.

Built-in bibliography, how to import BibTex, BiblaTex, etc. file?
#18

Perhaps this might better be discussed in a new topic rather than taking over someone else’s discussion? You could of course add a link to this discussion for context.

#19

Clearly, no.
Writer bibliography inserts “keys” into a document and creates a table of “keys” with their description. And maintaining the key/description database is quite a pain.
Zotero goes far beyond that. It manages full text citations and more. Paradoxically, I’d say it inserts entries into a document app (Writer, Word, …) a bit by “accident”, as a “secondary” “minor” task. Its big job is citation management.

#20

Thanks for feedback. This is why my readiness to use Writer built-in bibliography function reduces to only one situation where one can build and maintain DB of used sources in a tool external to Writer, import the DB well-done to Writer’s bibliography DB, one can for every record external-side quickly find its pendant Writer-side, place citations and bibliography to document using Writer (motivation of Built-in bibliography, how to import BibTex, BiblaTex, etc. file?).

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.