Rewrite of Disambiguation section

[rmzelle]

More expansive rewrite, continuing on proposed changes in https://gist.github.com/1029888 (see also the gist's comment section).

[bdarcus]

As a general suggestion, when issue pull requests, you can include a note about how confident you are in the diff, and if you have concerns, you itemize them for comment?

[rmzelle]

I'm pretty confident in this one, but I would like a +1 from "Disambiguation Frank".

The main changes are

• the reason for disambiguation. https://github.com/citation-style-language/documentation/pull/16/files#L0L1378
• a better description of the behavior of disambiguate-add-names. Previously, the spec stated that all names are added when disambiguation by disambiguate-add-names fails. There was a sentence in the description of disambiguate-add-givenname stating that ultimately, added (and expanded) names that don't contribute to disambiguation are discarded again. The problem was that disambiguate-add-names can be used in the absence of disambiguate-add-givenname. This situation is now covered. https://github.com/citation-style-language/documentation/pull/16/files#L0L1395
• a more complete description of year-suffix disambiguation. https://github.com/citation-style-language/documentation/pull/16/files#L0L1479

I edited the rest of the text as well, but that should mostly concern style, not content.

[rmzelle]

Frank has looked over the changes, so I'm confident in merging the pull request.

[jannefleischer]

Hi,

I do have a follow-up question to the documentation regarding "disambiguation-add-year-suffix" (currently line 1611 to 1623). For me the documentation ins't clear when it comes to the following cites:

Should

Jon Doe 2007, Jon Doe 2007, Foo Bar 2008, Foo Bar 2008 result in Doe 2007a, Doe 2007b, Bar 2008c, Bar 2008d or in Doe 2007a, Doe 2007b, Bar 2008a, Bar 2008b

The first one is the implementation that papers2 is using, as far as I know. The second one is what I need. Maybe my english isn't good enough for the documentation, but it seem to be unclear in this matter.

I don't want to make this into a support-forum, but is there an other option I am not aware of that triggers the first or second behavior?

[rmzelle]

"Doe 2007a, Doe 2007b, Bar 2008a, Bar 2008b" is the only correct option, so if Papers is producing "Doe 2007a, Doe 2007b, Bar 2008c, Bar 2008d" that's a bug in their software. The suffixes should restart counting for each ambiguous set of cites (2x "Doe 2007", and 2x "Bar 2008").

Are you sure that you didn't cite "Bar 2008a" and "Bar 2008b" elsewhere in your document?

[jannefleischer]

Thanks for clearing this up. I'll contact them.

And yes, I am shure because my last cite gets an "h" as year-suffix.