Referencing authors in Specref

[xfq]

In our teleconference, the Internationalization WG actioned me with filing an issue to add "authors" to Specref references.

For the i18n WG/IG, "author" is the actual producer of the content, and "editor" only edits the content. We'd like to have authors listed before editors.

Some current examples (authors are not mentioned at all):

[alreq]
Richard Ishida. Arabic & Persian Layout Requirements. 12 December 2023. W3C Note. URL: https://www.w3.org/TR/alreq/ ED: https://w3c.github.io/alreq/

[klreq]
Richard Ishida. Requirements for Hangul Text Layout and Typography : 한국어 텍스트 레이아웃 및 타이포그래피를 위한 요구사항. 27 May 2020. W3C Note. URL: https://www.w3.org/TR/klreq/ ED: https://w3c.github.io/klreq/

[simple-ruby]
Florian Rivoal; Atsushi Shimono; Richard Ishida. Rules for Simple Placement of Japanese Ruby. 9 June 2020. W3C Working Draft. URL: https://www.w3.org/TR/simple-ruby/ ED: https://w3c.github.io/simple-ruby/

[tobie]

Happy to accept a PR that would do this and to discuss what strategy would be best to accomplish that goal.

[xfq]

It looks like there are only editors and no authors in https://www.w3.org/2002/01/tr-automation/tr.rdf (which is the source of Specref).

[tobie]

Does W3C’s API support it?

[xfq]

cc @deniak

[deniak]

Does W3C’s API support it?

No, W3C actually only records/expose the list of editors (e.g. alreq editors).
Pubrules only requires the list of editors so a lot of specs don't even specify the authors list or it's probably merged with the editors.
Note that the process document only has some requirements on the editors.

[tobie]

Path of least resistance here seems to be to add more people as editors? You could do this either in the spec itself or as an “overwrite” in specref.

[marcoscaceres]

I agree... hardly any working group uses "authors".... editors are more often than not the authors.

[frivoal]

I think it's more common with Notes than with specs, as it can happen that a document is someone(s) summarizing their personal expertise and offering it to the group, where the group and its editors vet the content and massage it into convenient shape (possibly including translating it), while respecting the original author's take on things. The original author could be an editor too, but sometimes is not, for a variety of reasons (such as not speaking English).

[r12a]

Path of least resistance here seems to be to add more people as editors? You could do this either in the spec itself or as an “overwrite” in specref.

That leads to the problem we're trying to solve, if i understand correctly what you're suggesting. (A bit like the song "There's a hole in my bucket", if you know that.)

The problem is that, due to a very recent change to publication rules, it's not possible to publish a document using echidna if named 'editors' are no longer part of the working group. In order to publish alreq i had to move all the people we previously called editors to the author list, leaving just myself as an editor (fwiw i also appear under the Author list).

Actually, though, this doesn't seem mo to be a bad way to proceed. I think we have long been using the term 'editor' rather strangely at the W3C. I think it makes sense to list one or maybe two people only as editors – ie. they are responsible for gating PRs, and publishing the document, and maintaining editorial control. I don't think it's normal to have a cast of thousands for that. The people who provide or help shape the content are properly referred to as 'authors'. In some cases, these people could actually be much more important than an editor.

So i think we need to reassess how we use the terms 'editor' and 'author' for W3C specs.

However, the immediate practical need here is to adapt respec so that the names of the people moved to the 'Author' field (so that we could publish the document) receive the appropriate recognition in references.

hth

[tobie]

This can be solved by adding a dedicated "overwrite".

[tobie]

See how the overwrite system works here: https://github.com/tobie/specref/blob/main/CONTRIBUTING.md#overwrite-files-for-auto-generated-data-corrections

[xfq]

This method seems to require manual synchronization of the author list in the spec and the author list in Specref. Although it solves the problem, it goes against the original intention of Specref (automation).

[tobie]

Yeah, that’s a workaround.

[r12a]

Fwiw, here's what we currently do for I18n WG documents. (We make these changes when a document needs editing, so not all of our documents use this approach yet, but they will eventually. Some documents have an h3 section inside the Introduction, but we plan to change that.)

We use the editors list to list only those people currently managing updates to the document – usually just one or two people.

The body of the text begins with an h2 section "Contributors" (ie. before the Introduction), where we list the original authors and anyone else who provided substantive contributions to the document, alongside descriptions of how they contributed. This is much better than a simple list of 'authors', because it clarifies how people contributed. Having an h2 heading at the beginning of the document also gives better acknowledgement to contributors.

Here's an example: https://www.w3.org/TR/alreq/

Of course, what doesn't occur is that an author's name appears automatically in lists or references pointing to the document.

[tobie]

One option would be to create ./overwrites/w3c.json with the following content and do so for each spec.

[
    {
        "id": "alreq",
        "action": "replaceProp",
        "prop": "authors",
        "value": [
            "Behnam Esfahbod",
            "Mostafa Hajizadeh",
            "Najib Tounsi",
            "Richard Ishida",
            "Shervin Afshar",
            "Titus Nemeth"
        ]
    },
    {
        "id": "arabic-math",
        "action": "replaceProp",
        "prop": "authors",
        "value": [
            "Azzeddine Lazrek",
            "Mustapha Eddahibi",
            "Khalid Sami",
            "Bruce R. Miller"
        ]
    }
]

This would also avoid you having to maintain local bibliographies in ReSpec.