ropensci/RNeXML — pull request #78 by fmichonneau (2014-07-25 18:03:57+00:00)
Title: a few (minor) edits/comments to manuscript

Hi,

I went through the manuscript quickly, and provided some edits/comments. RNeXML is really exciting and the manuscript provides nice examples of how powerful and useful this package is. Below are a few additional comments.

- I think the manuscript will benefit from having a quick paragraph about some details of the XML file format. The manuscript does a good job at emphasizing that XML is well suited to store data/metadata associated with phylogenetic studies, but the manuscript lacks a section on how a XML file is organized and the definitions of some concepts that are used in the manuscript. For instance, in the section "Custom metadata extensions", the second paragraph reads:

> "We see the title appears as the value of the `content` attribute of this `meta` element."

half of the words in this sentence are mentioned for the first time here (or have been used but not defined), and it is also the first time in the manuscript that the actual content of an XML file is shown. I realize that one of the advantages of this package is to not have to deal with XML files _per se_, but providing, in the introduction, a brief overview of the XML format and a definition of some of the concepts of the terms used would clarify the manuscript.

- in the same section, there is a discussion about prefixes. Providing a few sentences about the use of prefixes in XML would be useful. Currently, the reader is left wondering why there is a `dc`, a `prism` and a `skos` prefix and what could be the difference between them. Talking about the scope of each namespace, and why several need to be used would be useful. Maybe bringing in Darwin Core that many people would have heard of might also be worthwhile.

- I edited this in a couple of places in the manuscript, but I think in general that it's better to tell the reader what a command is going to do beforehand (see l. 508-510 of my commit)

- it's a detail but sometimes APE's `phylo` class is referred to as `ape::phylo` and other times as just `phylo`, and simmap is also sometimes `simmap`

- it might be beyond the scope of the manuscript but there are some nice possibilities for phylobase and RNeXML to interact. As phylobase provides classes that store together trees + data (and has a slot to store metadata), there are definitely some interesting possibilities to pass data around.

Let me know if you have any questions or need additional feedback.