Heading interface for documentclasses

[moewew]

As mentioned in #685 it might be a nice idea to offer a standardised interface for classes to influence the bibliography headings.

Ideas and comments are very welcome.

[moewew]

At the moment we copy the standard definitions for the standard classes, memoir and older (<=v3.24) versions of KOMA. While for newer KOMA (>=v3.25) we use the \bibliography@heading command provided by that class. This command obeys all of KOMA's bibliography options.

I guess if we wanted other document classes to do something similar we would have to specify the expected implementation details and would have to document that.

@u-fischer Also suggested an interface for classes or style files to change the default heading used (e.g. use bibintoc instead of bibliography). This might not be a solution to the mess that are headers, but is interesting nevertheless.

See also #627

[u-fischer]

Imho the \bibliography@heading interface looks a bit indecisive and inflexible. E.g. assume a user ask that the heading of the bibliography and the biblist differ ....

Also I generally prefer if packages offer an interface which classes or other styles can use, instead of trying to adapt themselves to (all) existing classes. Assume that someone is writing somewhere a shiny new class, which uses completly different commands for the headings (e.g. in cyrillic as the class is based on a unicode engine) and wants to support biblatex ...

[moewew]

So I had a look at this yesterday night (it might have been a bit late, so please tell me if I'm making a stupid mistake here) and decided to implement an interface where a class developer could supply a default definition for the heading and a default title. Essentially

\defbibheading{bibliography}[\csuse{abx@clsinterface@heading@bibliography@title}]{%
    \csuse{abx@clsinterface@heading@bibliography}{#1}}

I decided to go for only one macro instead of three or more more specialised macros (as suggested here), because I felt that one macro would reduce the overhead on the biblatex side and potentially also for the class (only defined one macro and not three), additionally I thought that one multi-purpose macro could make the entire process more flexible.

A first attempt is in https://github.com/plk/biblatex/compare/dev...moewew:headinginterface

But then it struck me: As I implemented it, that is actually a needlessly complicated wrapper around \defbibheading. Why don't we just tell class developers to use \defbibheading, surely that already is the interface at least I had in mind? It might remain to make \blx@theheading (the default heading that \printbibliography uses) customisable, but then classes could modify \defbibheading{bibliography} directly to get that...

@u-fischer Thoughts?

[u-fischer]

Well one problem with telling class writers to use \defbibheading is that \defbibheading isn't yet defined when the class is loaded. This means that class writers would have to do something like \AtBeginDocument{\@ifpackageloaded{biblatex} or \AfterPackage{biblatex}.

I'm developing quite an aversion against all this conditional code as it makes it more and more difficult to understand which definition is actually winning under which condition and forces users to use \AtBeginDocument more and more often. Imho if possible a simple linear line of definitions and redefinitions should be used and packages should do their job when loaded and not in various other places too.

So I'm advocating for something like this:

\providecommand\abx@clsinterface@heading@bibliography[1]{whatever}
\defbibheading{bibliography}[\csuse{abx@clsinterface@heading@bibliography@title}]{%
   \csuse{abx@clsinterface@heading@bibliography}{#1}}

class and package writers can then use without any tests

\def\abx@clsinterface@heading@bibliography#1{whatever}

and the last one will win. And users can either use this internal commands too, or simply redefine with \defbibheading the complete heading.

[moewew]

Ah, that is a very good point. Thank you very much. I guess https://github.com/plk/biblatex/compare/dev...moewew:headinginterface is already on the right track then.

[moewew]

Additional code to let the document class define blx@theheading is at https://github.com/plk/biblatex/compare/dev...moewew:moreheading (changes against the headinginterface branch: https://github.com/moewew/biblatex/compare/headinginterface...moreheading)