References best practices

[apowers313]

The docs provide a good overview of how to submit new references, but I haven't found anything on "best practices" of what a reference should look like. For example, the IANA-COSE was originally a reference called IANA-COSE-ALGS-REG in the FIDO specifications, and the FIDO reference was to a specific section of the IANA spec.

Another set of odd links from FIDO are to the Bluetooth specifications:

    "BTCCC": {
        "publisher": "Bluetooth SIG",
        "title": "Client Characteristic Configuration. Bluetooth Core Specification 4.0, Volume 3, Part G, Section 3.3.3.3",
        "href": "https://www.bluetooth.com/specifications/adopted-specifications"
    },
    "BTCORE": {
        "publisher": "Bluetooth SIG",
        "title": "Bluetooth Core Specification 4.0",
        "href": "https://www.bluetooth.com/specifications/adopted-specifications"
    },
    "BTDIS": {
        "publisher": "Bluetooth SIG",
        "title": "Device Information Service v1.1",
        "href": "https://www.bluetooth.com/specifications/adopted-specifications"
    },
    "BTGAP": {
        "publisher": "Bluetooth SIG",
        "title": "Generic Access Profile. Bluetooth Core Specification 4.0, Volume 3, Part C, Section 12",
        "href": "https://www.bluetooth.com/specifications/adopted-specifications"
    },
   // ...

You'll note that they have the same URL, but the titles of the references point to specific section numbers. The URL doesn't even link to the specification itself, but links to a landing-page that seems to have a non-stable URL for a PDF...

If I were to submit these references in their current form (duplicate URLs, section names in titles, links to specific sections, etc.) would that be a black mark upon my name? Would the changes be rejected? Or is it really "anything goes"?

[tobie]

So Specref will balk over duplicate URLs. I don't have a good solution for this issue, tbh. :-/

[tobie]

I've thought this through a little more and can now expand on my previous comment a bit.

First of all, fragment URLs aren't considered as duplicates so you should be fine in the IANA spec example you mention earlier.

For the Bluetooth case, your best bet is to create a single BTCORE reference and be specific in how you reference it, e.g.:

… see Client Characteristic Configuration of the Bluetooth Core Specification 4.0, Volume 3, Part G, Section 3.3.3.3. [[!BTCORE]]

I know this isn't optimal, so if you're using those references all over the place, we could somehow special case BTCORE, but frankly I'm concerned about the precedent that would create.

Alternatively, you could toy with abusing versions to provide a similar solution. I'm not sure whether that would work, though. The idea would be to create versions of the spec that would just specify a different title, but no href, and then reference them as: [[BTCORE-CCC]].

That's sort of an aside, but why not link to the real things? Are the URLs to the PDFs not stable? E.g.:
https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=421043

[apowers313]

I'm assuming that the URLs to the PDFs aren't stable (they really look like they belong to some CMS that could change...). But even if the URLs were stable, BTCORE, BTCCC, BTDIS (and others) are really all just different sections of the same document. In looking through the current bibliography, there are some examples of references to sections (although I don't recall them now).

My meta-question is whether there are any rules of what should / shouldn't be submitted as references. Sounds like it's not really formal and it's more common sense and / or on a case-by-case basis?

[tobie]

My meta-question is whether there are any rules of what should / shouldn't be submitted as references. Sounds like it's not really formal and it's more common sense and / or on a case-by-case basis?

Yes. Plus there's a test suite that's automatically run and that will prevent you from doing a bunch of things (such as having identical URLs for multiple entries).