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.

Received on Tuesday, 27 May 2025 13:35:13 UTC