Re: Citation and bibliography technologies - references

Thank you, Ken, for the detailed work and commentary. Your notes regarding the output are consistent with what I would expect. We’ll review your example.

I think the main question now is whether the current output satisfactorily conforms to W3C publication style rules, and if not, whether it can be adjusted in the underlying XML definitions used by citeproc-js to create the citations and bibliography entries.

From: Ken Franqueiro <kfranqueiro@w3.org>
Date: Monday, May 19, 2025 at 15:03
To: Jason J.G. White <jason@jasonjgw.com>
Cc: public-rqtf@w3.org <public-rqtf@w3.org>
Subject: Re: Citation and bibliography technologies - references

Here is the output of my proof-of-concept implementation so far,
containing both sets of records I've received:

https://gist.githack.com/kfranqueiro/4739161e94da9cd64b65291274d3b62f/raw/5504eb0277f7a0bbae59a172a2b51dd043d1b2be/ED-20250519.html#references

This populates localBiblio from the parsed BibTeX records, then replaces
the HTML in each dd generated by ReSpec with the HTML generated by
citeproc-js through citation.js. For testing purposes, I scripted a
paragraph that would reference every localBiblio entry to force them all
to be output under References.

Notes/questions:

1. I assumed that the HTML generated by citeproc-js would be a better
starting point than trying to feed data into ReSpec's own References
section generation; the latter would require us specifically feeding
e.g. journal titles, volume/number/pages, etc. into the few fields that
ReSpec's biblio format supports, which wouldn't be a particularly clean
mapping (e.g. cramming multiple fields into title) and could require us
to figure out a lot of edge cases per reference type.

2. A couple of things to point out about citeproc's formatting: it
italicizes journal names and volume numbers (using i tags, not em),
meanwhile it does not do anything to article titles. I wrapped each
title in a cite element as part of the pre-processing script, to match
ReSpec's typical behavior for References. Let me know if we want to make
adjustments to this.

3. ReSpec re-orders References populated from its biblio database in
alphabetical order; this includes ordering e.g. RN11 before RN2. Are we
okay with this, or would we rather force it to match the order found in
the BibTeX output?

4. Note that this involves no manual tweaks; all of this is scripted.
There is no intermediate data file; this is all done through ReSpec
pre-process and post-process steps. This has the upsides of not crowding
the repo with an auto-generated file, and not requiring manual
intervention every time it is generated. However, this does mean any
tweaks would need to be built into the script, so let me know if
anything seems off in the output so far.

Thanks,
--Ken

On 2025-05-18 10:21 am, Jason J.G. White wrote:
> Thank you, Ken, for working on this issue - answers appear in-line
> below.
>
>
> On 15/5/25 13:14, Ken Franqueiro wrote:
>>
>> 1. Will each of these records be specifically cited at some point
>> within the document?
> Yes, as is standard practice in scholarship and, as I understand it, in
> W3C publications as well.
>> 2. Is it expected that the entries currently under the Reference List
>> section will ultimately be generated from the BibTeX output?
>>
> Yes, we intend to remove the current (manually created) References
> section and to generate the entire bibliography from BibTeX records in
> a later draft. In future publications, we would also use BibTeX
> records. We're trying to eliminate the problem of manually writing and
> maintaining ReSpec JSON records, especially in view of the fact that
> the data can be trivially exported in BibTeX format (and several other
> formats) from public databases such as scholar.google.com. Even if we
> have to correct errors in the entries, it's still less work than
> manually converting everything to a custom (ReSpec) JSON format
> supported by none of the online bibliographical database systems
> besides W3C's own.