Table of formatters

[tobiasdiez]

This issue summarizes all the available formatters.
The aim is to improve their names and descriptions.
I think the most practicable way is to directly edit this post with the new proposed version.

Class Name	Key	Name	Description
AuthorsFormatter	AuthorsFormatter	BibTex authors format	Normalizes lists of persons in %s to the BibTeX standard
UpperEachFirst CaseChanger	UpperEachFirst CaseChanger	Upper Each First	Converts the first character of each word in %s to upper case (and all others to lower case), but does not change words starting with "{".
UpperCaseChanger	UpperCaseChanger	UPPER	Converts all characters in %s to upper case, but does not change words starting with "{"
MonthFormatter	MonthFormatter	Month	Normalizes content of %s to the format #mon#.
LatexFormatter	LatexFormatter	Latex	Cleans latex code in %s.
UpperFirst CaseChanger	UpperFirst CaseChanger	Upper first	Converts the first character of the first word in %s to upper case (and the remaining characters of the first word to lower case), but does not change anything if word starts with "{".
AuthorsMinifier	MinifyAuthors	Minify authors	Replaces three or more authors with "and others".
DateFormatter	DateFormatter	Date	Normalizes dates in %s to the BibLaTeX standard yyyy-mm-dd or yyyy-mm.
TitleCaseChanger	TitleCaseChanger	Title	Converts all words in %s to upper case, but converts articles, prepositions, and conjunctions to lower case.
CaseKeeper	CaseKeeper	CaseKeeper	Adds {} brackets around acronyms, month names and countries in %s to preserve their case.
PageNumbers Formatter	PageNumbers Formatter	Page numbers	Ensures that pages numbers in %s are of the form num--num.
LowerCaseChanger	LowerCaseChanger	lower	Converts all characters in %s to lower case, but does not change words starting with "{"
TrimFormatter	TrimFormatter	Trim whitespace	Removes any leading and trailing whitespace in %s.
HTMLToLatex Formatter	HtmlConverter HtmlToLatex	HTMLConverter HTML to LaTeX	Changes HTML expressions in %s to their LaTeX equivalent.
SuperscriptFormatter	SuperscriptFormatter	Superscripts	Transforms ordinal numbers in %s into LaTex superscripts.
UnitFormatter	UnitFormatter	UnitFormatter	Converts units in %s to LaTeX code.
RemoveBraces Formatter	RemoveBraces Formatter RemoveBraces	Remove enclosing double braces	Removes all matching braces around the contents of %s.
UnicodeToLatex Formatter	UnicodeConverter UnicodeToLatex	UnicodeConverter Unicode to LaTeX	Converts unicode characters in %s to their LaTeX equivalent.
EraseFormatter	EraseFormatter Erase	Erase all Erase field	Completely erases %s.

Remarks:

• The key is used for the serialization.
• The name should be used for example in the drop down box. Note: some names are also used in the context menu which appears on right-clicking a text field in entry edit. Which explains the shorter and somewhat cryptic names for example the UpperCaseChanger.
• The description is shown as a tooltip.
• (I added some spacing in the classname and key so that the columns are not super-wide)

[mlep]

I have just removed a duplicated formatter

[simonharrer]

• AuthorsFormatter
  • classname: NormalizeAuthorsFormatter
  • key: normalize_authors
  • name: Normalize authors
  • description: Normalizes lists of persons in %s to the BibTeX standard.
  • example: "Albert Einstein and Alan Turing" to "Einstein, Albert and Turing, Alan"
• UpperEachFirstCaseChanger
  • classname: CapitalizeFormatter
  • key: capitalize
  • name: Capitalize
  • example: "I have {a} DREAM" to "I Have {a} Dream"
• UpperCaseChanger
  • classname: UpcaseFormatter
  • key: upcase
  • name: to upper case
  • example: "Google {Chrome}" to "GOOGLE {Chrome}"
• LowerCaseChanger
  • classname: DowncaseFormatter
  • key: downcase
  • name: to down case
  • example: "Google {Chrome}" to "google {Chrome}"
• MonthFormatter
  • classname: NormalizeMonthFormatter
  • key: normalize_month
  • name: Normalize month
  • example: "December" to "#dec#"
• LatexFormatter
  • classname: RemoveLatexFormatter
  • key: remove_latex
  • name: Remove LaTeX
  • desc: Removes all latex constructs and code in %s.
  • example: "\textbf{asdf}" to "asdf"
• UpperFirstCaseChanger
  • classname: CapitalizeFirstFormatter
  • key: capitalize_first
  • name: Capitalize first
  • example: "i have {Aa} DREAM" to "I have {Aa} dream"
• AuthorsMinifier
  • key: minify_authors
  • classname: MinifyAuthorsFormatter
  • example: "Stefan Kolb and Simon Harrer and Guido Wirtz" to "Stefan Kolb and others"
• DateFormatter
  • key: normalize_date
  • classname: NormalizeDateFormatter
  • name: Normalize date
  • example: "1.1.16" to "2016-01-01"
• TitleCaseChanger
  • key: titelize
  • name: Titelize
  • description: Capitalize all words in %s, but converts articles, prepositions, and conjunctions to lower case.
  • example: "{BPMN} conformance In open source ENgines" to "{BPMN} Conformance in Open Source Engines"
• CaseKeeper
  • key: freeze_terms
  • name: Freeze terms
  • example: "In December" to "In {December}"
• RemoveBracesFormatter
  • key: unfreeze_terms
  • name: Unfreeze terms
  • example: "In {December}" to "In December"
• PageNumbersFormatter
  • key: normalize_pages
  • classname: NormalizePagesFormatter
  • name: Normalize pages
  • example: "1 - 2" to "1--2"
• TrimFormatter
  • key: trim
  • maybe remove this? to be discussed in devcall?
• HTMLToLatexFormatter
  • key: html_to_latex
  • name: HTML to LaTeX
  • classname: HtmlToLatexFormatter
  • example: "asdf" to "\textbf{asdf}"
  • usage?
• SuperscriptFormatter
  • key: ordinals_to_latex
  • classname: OrdinalsToLatexFormatter
  • name: Ordinals to LaTeX
  • example: "11th" to "11\textsuperscript{th}"
• UnitFormatter
  • key: units_to_latex
  • classname: UnitsToLatexFormatter
  • name: Units to LaTeX
  • example: ?
• UnicodeToLatexFormatter
  • key: unicode_to_latex
  • name: Unicode to LaTeX
  • classname: UnicodeToLatexFormatter
  • example: ?
• EraseFormatter
  • key: clear
  • name: Clear
  • classname: ClearFormatter
  • example: "Anything" to ""

[stefan-kolb]

What is related to this PR is that we should have a clear QA what is required to include a new formatter.
Several formatters should be removed IMHO. Our product transitions into being more well-structured in terms of code quality but does not focus much on improving usability for the end users.

• We should not unecessarily increase the number of formatters, but limit our range to "good" formatters
• Formatters should have a clear use case that is applicable for a wider range of users, not obscure use cases for individuals
• The use case and functionality must be clear to the user. So what to expect from the formatter? e.g. a Unitformatter does not state which units it will apply to
• Formatters should be well tested and be applicable for (almost) all cases that may apply, e.g. a html formatter capable of formatting only text as \textbf{} makes no sense.

Therefore, I propose to remove/improve the following formatters:

• AuthorsFormatter: needs to be improved to be able to handle at least Latex umlauts, e.g. J{"o}rg
• UppercaseChanger: Remove this formatter. I don't see any use case where I want to upcase my fields
• CaseKeeper: Which terms are frozen?
• TrimFormatter: We should trim() all fields in the entry by default. I don't see any reason why one wants to have spaces at the beginning or end of an BibTex field.
• HTMLToLatexFormatter: What cases can this formatter handle? It's unclear to the user. I don't think it is good enough to stay in the game.
• UnitFormatter: what units can this formatter convert? It's unclear to the user. I'd remove it or implement ALL standard LaTeX units, if there is such a list.
• UnicodeToLatex: Is it good enough? What cases does it handle?

Comments and changes welcome!

[stefan-kolb]

@JabRef/developers As this is a blocker for v3.3 (especially the keys for avoiding migrations later on) all of you should have a look.

[oscargus]

@stefan-kolb Have your tried the HTML/Unicode to Latex (or back, layout formatters) converters recently? :-)

I'd say it is probably the best/most complete open source converter suite available (beaten only by Latex when it comes to Latex to Unicode...).

The unit converter handles all SI units and quite a lot of derived ones. Would be a shame to remove it as it provides automatic proper formatting for quite a lot of cases.

Case keeper is very EE focused at the moment (since I wrote it and probably has been the only one adding words and abbreviations to it). Since IEEE now provide quite OK bracing, the need is reduced for it. Still, I'd say keep and later make it configurable for people to add their own words. To automatically be able to add braces to the correct words (as opposed to all capital letters) is far superior. Even after running some case converter.

The authors formatter should use one of the two already existing, far superior, methods to format names. Author list or even better the one in bst.

In general, usability is quite user dependent. There are a few for matters I will never ever use and a few which you have rendered useless that I use regularly...

[stefan-kolb]

@oscargus Like I said I'm open for suggestions. I'd just took a look from a customers point of view at first. Haven't evaluated the code of each Formatter.

[stefan-kolb]

So what about UppercaseChanger and TrimFormatter at least?

[tobiasdiez]

I think the UppercaseChanger can be removed. The only application I see is that this formatter is used in the generation of cite-keys, where it might make sense (but again, then this is not a Formatter but a LayoutFormatter).

Regarding the TrimFormatter So far we had the "don't change the contents of the fields until asked to do so"-policy. On the other hand, I find it reasonable to always trim the field contents.

[koppor]

My following list is based on Simon's. Additionally, I also did some sorting and also did add classnames

I like the CamelCase key names, therefore I put CamelCase there.

Regarding the name: I think, it reads strange, if we have a name with two words and the first word is sometimes capitalized and sometimes not. Therefore, I write everything in lower case.

Questions:

Regarding FreezeTerms and UnfreezeTerms: This are no opposite formatters. Therefore, I included "UnfreezeWords". Maybe "UnfreezeAllWords" would be better?

I really vote for keeping AuthorsFormatter as it is a different thing than AuthorList and is more powerful. See #950.

UpperCaseChanger: We can convert them to a LayoutFormatter.

TimFormatter: +1 for always trimming during writing an entry.

Authors related

• AuthorsFormatter
  • classname: NormalizeAuthorsFormatter
  • key: NormalizeAuthors
  • name: normalize authors
  • description: Normalizes lists of persons in %s to the BibTeX standard.
  • example: "Albert Einstein and Alan Turing" to "Einstein, Albert and Turing, Alan"
• AuthorsMinifier
  • key: minify_authors
  • classname: MinifyAuthorsFormatter
  • example: "Stefan Kolb and Simon Harrer and Guido Wirtz" to "Stefan Kolb and others"

Date related

• MonthFormatter
  • classname: NormalizeMonthFormatter
  • key: NormalizeMonth
  • name: normalize month
  • example: "December" to "#dec#"
• DateFormatter
  • classname: NormalizeDateFormatter
  • key: NormalizeDate
  • name: normalize date
  • example: "1.1.16" to "2016-01-01"

Page related

• PageNumbersFormatter
  • key: NormalizePages
  • classname: NormalizePagesFormatter
  • name: normalize pages
  • example: "1 - 2" to "1--2"

Casing related

• TitleCaseChanger
  • key: titelize EnforceTitleCase
  • name: Titelize EnforceTitleCaseFormatter
  • description: Capitalize all words in %s, but converts articles, prepositions, and conjunctions to lower case.
  • example: "{BPMN} conformance In open source ENgines" to "{BPMN} Conformance in Open Source Engines"
• UpperEachFirstCaseChanger
  • classname: CapitalizeFormatter
  • key: Capitalize
  • name: capitalize
  • example: "I have {a} DREAM" to "I Have {a} Dream"
• UpperCaseChanger
  • classname: UpcaseFormatter
  • key: upcase
  • name: to upper case
  • example: "Google {Chrome}" to "GOOGLE {Chrome}"
• UpperFirstCaseChanger
  • classname: CapitalizeFirstDowncaseOthersFormatter
  • key: CapitalizeFirstDowncaseOthers
  • name: capitalize first, downcase others
  • example: "i have {Aa} DREAM" to "I have {Aa} dream"
• LowerCaseChanger
  • classname: DowncaseFormatter
  • key: Downcase
  • name: to down case
  • example: "Google {Chrome}" to "google {Chrome}"
• CaseKeeper
  • class: FreezeTermsFormatter
  • key: FreezeTerms
  • name: freeze terms
  • example: "In CDMA" to "In {CDMA}"
• RemoveBracesFormatter
  • key: UnfreezeWords
  • name: unfreeze words
  • example: "In {CDMA}" to "In CDMA"

LaTeX conversion

• LatexFormatter
  • classname: RemoveLatexFormatter
  • key: RemoveLatex
  • name: remove LaTeX
  • desc: removes all latex constructs and code in %s.
  • example: "\textbf{asdf}" to "asdf"
• HTMLToLatexFormatter
  • key: HTMLToLaTeX
  • name: HTML to LaTeX
  • classname: HtmlToLatexFormatter
  • example: "asdf" to "\textbf{asdf}"
  • usage?
• UnicodeToLatexFormatter
  • key: UnicodeToLatex
  • name: Unicode to LaTeX
  • classname: UnicodeToLatexFormatter
  • example: "Mönch" to "M"{o}nch"
• SuperscriptFormatter
  • key: OrdinalsToLatex
  • classname: OrdinalsToLatexFormatter
  • name: ordinals to LaTeX
  • example: "11th" to "11\textsuperscript{th}"
• UnitFormatter
  • key: UnitsToLatex
  • classname: UnitsToLatexFormatter
  • name: Units to LaTeX
  • Add hard spaces, non-breaking hyphen, and freezing to units
  • example: "1 Hz" to "1~{Hz}"

Radical formatters

• TrimFormatter
  • key: trim
  • maybe remove this? to be discussed in devcall?
• EraseFormatter
  • key: clear
  • name: Clear
  • classname: ClearFormatter
  • example: "Anything" to ""

[koppor]

We have to be sure, what UnicodeToLaTeX does. When reading the first sentence of #809 possibly, LaTeXToUnicode seems to be the right name.

[matthiasgeiger]

I'm quite satisfied with the proposals of Simon and Olly.
Some few aspects:

• "Titelize" - this is not really an english word... "title case" is the normal term for this
• "FreezeTerms"/"UnfreezeWords"...: I don't like this. How about: Lock Term Casing? or: Preserve Term Casing? (Regardless what we'll choose this a hell to translate to German ;-))
• "downcase": Why not "lowercase" which is used far more frequently?

[koppor]

• Titelize -> EnforceTitleCase?
• OK for LockTermCasing. "Lock" is better than "Preserve", because JabRef doesn't preserve it itself. It justs ensures that it is preserved. EnsurePreservingCaseOfTerms is too long for me.
• OK for lowercase