A first look at function builder about build.eml

[jeanetteclark]

This looks great! I have two comments:

1. For classes where the text value is duplicated (eg userID) it would be nice if the duplicated value was included as an argument in the function. This would enable you to do something like this:

jc_contact <- creator(individualName = 
                        individualName(givenName = "Jeanette", surName = "Clark"),
                      electronicMailAddress = "[email protected]", 
                      userId = userId(userId = "an orcid", directory = "https://orcid.org"))

as far as I can tell, currently you would have to add that in like this:

jc_contact$userId <- userId(directory = "https://orcid.org")
jc_contact$userId$userId <- "an orcid"

2. I would love to see good, valid examples in the documentation for each function. I think the datateam can help generate some of these if needed, they would be hugely beneficial to our team. Particularly with some of the more complex elements, you can spend a lot of time banging your head against the wall with validation errors as you are learning.

[mbjones]

@cboettig After a quick perusal, I think this looks awesome. I haven't had time to try it out, but we could ask some folks on the data team at NCEAS that use the package daily for feedback.

Regarding parsing XSD files... are you building your own parser, or using an XML Schema conformant parser? Such a parser should manage all of the cross file imports and referencing seamlessly, and provide access to all of the schema components programatically. These are available in the post-schema-validation infoset (PSVI) from the parser (for example, the Java Xerces parser provides functions for retrieving all xml schema components through their XML Schema API. See the XML Schema Abstract Model for the list of schema components, as well as the XML schema UML diagram showing what schema components should be accessible from the parser.

In terms of package naming conflicts, I suggest that prefixing all of the function names would help minimize conflicts (e.g., use eml_title() or md_title() rather than title()) and it would help group all of the related functions together in help indices.

[amoeba]

This is interesting!

Overall those docs look good but I think I'd want them to be more helpful with respect to guidance on what type of thing should be passed for each argument. For example, if I look at the dataset page, the help for alternateIdentifier is just "A secondary identifier for this entity". I think this could be improved in two ways:

1. Give a little more guidance on how to fill this out, either in-line or as a link to a richer resource. This isn't actually a problem with build.eml but just our docs in general (I think). build.eml could simply expose that extra info if we take the time to author it somewhere.
2. Provide a type. For alternateIdentifier, we'd expect character, but, say, for creator, can I pass in a return value from creator() or a person() call?

Do you think (2) could be done automatically or would there be some gluing to do there?

[cboettig]

thanks @amoeba !

Re the documentation detail, that's probably largely because we're just grabbing the summary section of the docs so far. However, there are some places where the XSD documentation itself is too thin or possibly missing entirely

Re 2, yeah, we could probably improve on that. Currently I've just updated the docs to attempt to link to the corresponding constructor (e.g. see https://cboettig.github.io/build.eml/reference/eml.html ) but I agree we could do more with typing.

Both of these come down to mostly needing more parsing of the XSD. @mbjones I'm just using the xml2 R package, which is just binding libxml2-dev libraries, so all my parsing is just XPATH expressions. Thanks much for these links, I'll dig in and see if they can help me.

[amoeba]

Re the documentation detail,...

Makes sense. We've slowly found gaps in the in-schema docs but that's been piecemeal and there are definitely some big gaps remaining.

Currently I've just updated the docs to attempt to link to the corresponding constructor

🎉 nice!