Re: Citation and bibliography technologies - references

Thank you, Ken, for continued work on our citation and bibliography generation.

I note that some of my examples were taken from non-W3C publications, where expectations for citations were different (e.g., specifying “World Wide Web Consortium” as the corporate author) from what would be expected in W3C publications. As long as all of the BibTeX fields appearing in the examples are properly treated in the generated bibliography, I think we have a good selection of cases to demonstrate that your tool is processing the bibliographical records appropriately. The remaining issues for authors and editors are then a matter of ensuring the data are correct in the BibTeX records (according to W3C expectations), with the generated bibliography reflecting the appropriate style in the generated HTML.


From: Ken Franqueiro <kfranqueiro@w3.org>
Date: Tuesday, May 27, 2025 at 09:35
To: Janina Sajka <janina@rednote.net>
Cc: public-rqtf@w3.org <public-rqtf@w3.org>
Subject: Re: Citation and bibliography technologies - references

I reached out to a few other W3C Staff (starting with Kevin) for
feedback about the citation format. The common answer was that there is
no single mandated format; even ReSpec and Bikeshed differ between each
other in how they format entries, and both are commonly used.

Some general advice is available in
https://www.w3.org/guide/manual-of-style/#References, including an
example references section. I would note the advice and examples here
differ somewhat from what is present in documents making use of specref
through ReSpec or Bikeshed, particularly in terms of how exactly they
present URLs, and how they cite editors without "eds." or "Editors."

I have updated my proof-of-concept to behave more like other documents
in how it presents URLs, by also wrapping the title in a link, and
prefixing the verbatim URL at the end with "URL:".

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

A few things specifically worth calling out regarding the BibTeX entries
provided in this thread (though I'm not sure how final they are intended
to be):

1. The atag20 entry lists the author as "World Wide Web Consortium",
when it should ideally list the editors of the document: Jan Richards;
Jeanne F Spellman; Jutta Treviranus. For any cases where you will be
citing standards, it would be worth checking against
https://www.specref.org/ to ensure you have complete information.

2. RN5's URL points to a login wall, seemingly with a specific customer
ID; is there a more broadly accessible link?

3. In value-sensitive-design: "Mit Press" should be "MIT Press"

--Ken

On 2025-05-19 7:08 pm, Janina Sajka wrote:
> +Kevin and Shawn because neither Jason nor I are the ones to answer
> regarding conformance to W3C style!
>
> Shawn, Kevin: We're thrilled by Ken's prompt and thorough work
> providing
> us with the tech to pipe bibtext citations into our W3C publications.
> As
> mentioned on today's CC call, this work is yielding results
> quickly--thanks to Ken!
>
> So, please help with the style question as below ...
>
>
> Jason J.G. White writes:
>> 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.