Ambiguous attributes in the author/affiliation schemas

[arnaudgallou]

Description

Quarto's author and affiliation schemas both have an attribute number. I find the name of that attribute ambiguous and would recommend using a more specific name (if possible) or explaining what these attributes are in the documentation.

I guess most people (myself included) understand the number attribute in the author schema as phone number. If this is what it actually is, wouldn't it be better to rename that attribute as phone-number instead?

Now the affiliation schema also has an attribute number and that is very confusing. Are we talking here of another phone number? If so, what's the difference with the one in the author schema? Is one number a personnal phone number and the other an office phone number? Or is it something else, e.g. the number of the office/room where the author works?

Not completely related but that would also be great to have a bit more details on the attribute acknowledgements. In my field (Natural Sciences), acknowledgements and authors are two distinct things. I've never seen an author who's also acknowledged so having some insights on how one should use that attribute (and what it actually does) would be helpful.

[dragonstyle]

We can improve documentation around these attributes - improvements to the author and affiliation schema documentation are coming soon!

I guess most people (myself included) understand the number attribute in the author schema as phone number. If this is what it actually is, wouldn't it be better to rename that attribute as phone-number instead?

It is actually a number assigned to author in the list (literally the number of the author). This is useful as often LaTeX title blocks need the ability to display author name and author data in separate locations of the title block. This often accomplished using a superscript number. This is merely a convenience for template authors.

Now the affiliation schema also has an attribute number and that is very confusing. Are we talking here of another phone number? If so, what's the difference with the one in the author schema? Is one number a personnal phone number and the other an office phone number? Or is it something else, e.g. the number of the office/room where the author works?

This, too, is an affiliation number, which is assigned based upon the order of affiliates. This, too, is provided as a convenience to coordinate affiliation names and data.

Not completely related but that would also be great to have a bit more details on the attribute acknowledgements. In my field (Natural Sciences), acknowledgements and authors are two distinct things. I've never seen an author who's also acknowledged so having some insights on how one should use that attribute (and what it actually does) would be helpful.

Currently that acknowledgements is a string that the author may provide any acknowledgements that they would like to make. I didn't see it currently used in any templates that we have authored, so I'm not sure I can tell you how it is used yet at least. Currently, the data is normalized and available to template authors if they render author acknowledgements.

[arnaudgallou]

Thanks, that's super useful. So if I understand correctly number is more like an index to help organize authors and affiliations in title blocks. That's definitely a piece of information to add to the doc IMO.

I'm a bit surprised there's no specific attribute for phone numbers in the author schema though given that there's a fax attribute, which is certainly less commonly used than phone number nowadays. Is there any recommended attribute to specify phone number? Metadata or simply use the fax attribute?

[dragonstyle]

Thanks, will do.

There is a phone attribute for authors, which looks like a documentation error. I would love to say that we're committed to only faxing over phone calls, but we're ok with either ;-)

[arnaudgallou]

Haha, right! Yep, currently phone isn't listed in the complete author schema.

[cwickham]

To followup, our improved Author and Affiliation documentation is now part of the Front Matter page under Guide > Scholarly Writing, at: https://quarto.org/docs/authoring/front-matter.html

[arnaudgallou]

This is great! I see there's now a key to assign roles. I definitely need to implement it in the package I'm currently developing. My package provides a flexible way to generate authors' contributions but its implementation is bit awkward when using Quarto's templates. A few questions before implementing it and to be sure I can ditch that feature in this case.

1. I assume the first example of the Author Roles section, using free form text, produces something like:

author_1 roles_author_1
author_2 roles_author_2

But can the roles key take an array of free form texts to produce contributions like in the 3rd example (aut_v) here?

author_1, author_2 and author_n role

2. When having multiple authors for a same role, is there a way to list authors' names in a custom order or are they only listed in the order they're defined in the YAML?

3. Contributions often use authors' initials rather than literal names. Does Quarto handle that automatically?

4. When using CRediT roles, can you confirm that lead and supporting are the only supported values? Can there be multiple lead authors for the same role or must the lead author be unique?

A few remarks:

• Some keys are mentioned in the Front Matter page but not in the Authors page and vice versa (e.g. number and metadata mentioned in Authors, not in Front Matter; roles and phone mentioned in Front Matter, not in Authors). I'd recommend listing the keys a bit more consistently between the two pages to avoid confusion.
• In the 14 Contributor Roles block, I presume the writing and editing aliases are inverted.

[dragonstyle]

Thanks for detailed questions and feedback - it is great to have another set of thoughtful eyes on this work!

1. I assume the first example of the Author Roles section, using free form text, produces something like:

I don't 100% follow here, but I will take a shot:

• You can provide an array of simple strings
• Roles are primarily here to be normalized for use in custom title blocks
• Most of our templates don't currently display roles. The one exception is our JATS output which will emit structured roles.
• The role the writer provides will ultimately be normalized into metadata like

  author: 
    roles: Array<{ role: text (or credit name), degree-of-contribution: (from CreDiT if provided) }>
  

Template or template partials could emit these roles in whatever way they would like.

2. When having multiple authors for a same role, is there a way to list authors' names in a custom order or are they only listed in the order they're defined in the YAML?

Currently there is no affordance for order - we just currently normalize the roles onto the author itself. In other places, we emit a denormalized schema organized to make it easier for template authors to iterate through data and emit their title blocks (e.g. by-author, by-affiliation), we could do the same for roles if that is useful. In addition, if important, we could consider adding some element of order to the role schema itself (.e.g. authors could specify a role, degree, and order).

3. Contributions often use authors' initials rather than literal names. Does Quarto handle that automatically?

We don't currently do anything for initials. We do normalize author names, which means that someone could write a LUA filter that normalizes names and attaches initials. It would be a pretty sweet enhancement for us to do this automatically if we could consistently produce reasonable initials.

4. When using CRediT roles, can you confirm that lead and supporting are the only supported values? Can there be multiple lead authors for the same role or must the lead author be unique?

Those values are treated opaquely by us and passed through verbatim. JATS provides examples of 'Lead' and 'Supporting', but we currently provide no special treatment for the value.

• Some keys are mentioned in the Front Matter page but not in the Authors page and vice versa (e.g. number and metadata mentioned in Authors, not in Front Matter; roles and phone mentioned in Front Matter, not in Authors). I'd recommend listing the keys a bit more consistently between the two pages to avoid confusion.

Thanks for these correction (esp roles and phone). Some items, like number and metadata are really there for developers writing LUA or templates using these schema. The number is automatically generated and unknown keys are automatically normalized into the metadata key. I'd expect some variance between the two mostly along the lines of whether we expect authors to actually write the value vs explaining to template developers how to use the values.

• In the 14 Contributor Roles block, I presume the writing and editing aliases are inverted.

That is correct - we'll fix!

[arnaudgallou]

Thank you so much for the detailed reply! You answered all my interrogations :)

It would be a pretty sweet enhancement for us to do this automatically if we could consistently produce reasonable initials.

Out of curiosity, what exactly is the issue with making consistent initials?

[cscheid]

Out of curiosity, what exactly is the issue with making consistent initials?

It probably falls into one of these: https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/