search

ropensci / RNeXML

Implementing semantically rich NeXML I/O in R
https://docs.ropensci.org/RNeXML
Other
13 stars 9 forks source link

write about the XML format in introduction #79

Closed fmichonneau closed 9 years ago

fmichonneau commented 10 years ago

Original comment:

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.

cboettig commented 10 years ago

@fmichonneau Thanks for pointing this out, definitely can't start throwing around words like 'attribute', 'value', and 'element' without defining them. I've tried to introduce them a bit more carefully in the modified text, lines 565-600 (though perhaps a figure would have served better?), and likewise for namespaces. If you have a chance, let me know what you think.

rvosa commented 10 years ago

Is it possible to have some kind of infobox or glossary in MEE manuscripts? Perhaps it is an idea to just define the necessary concepts ('attribute', 'element', 'namespace'...) in something like that, and then refer the reader to the wealth of verbiage that has already been written about XML in the life sciences (e.g. doi:10.1016/S0167-7799(00)01465-7 and http://books.google.nl/books?id=J0pdinIbxqEC)

rvosa commented 9 years ago

Hi guys,

it appears (at first glance :)) that there are only two outstanding issues for the manuscript milestone, neither of which have shown a lot of progress over the last month or so. Is there anything that I can/should do?

Rutger

cboettig commented 9 years ago

@rvosa Thanks for checking in. After my last read over in August I felt we were pretty much there (the basic xml concepts are now defined in text, though a box or such might indeed be better; the other issue is of course the generic thread on manuscript comments). @hlapp wanted some time to read over the latest copy before we submit. Planning to submit by the end of the month.

hlapp commented 9 years ago

I think the manuscript needs some more work. I'm doing a first pass with comments, and then we can plan for a conference call.

cboettig commented 9 years ago

@hlapp Sounds good, many thanks!

On Mon, Oct 6, 2014 at 10:53 AM, Hilmar Lapp notifications@github.com wrote:

I think the manuscript needs some more work. I'm doing a first pass with comments, and then we can plan for a conference call.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-58058834.

Carl Boettiger UC Santa Cruz http://carlboettiger.info/

cboettig commented 9 years ago

Hey @hlapp just wanted to check in where we are on this. Time to schedule a chat?

Carl Boettiger http://carlboettiger.info

sent from mobile device; my apologies for any terseness or typos On Oct 6, 2014 10:54 AM, "Carl Boettiger" cboettig@gmail.com wrote:

@hlapp Sounds good, many thanks!

On Mon, Oct 6, 2014 at 10:53 AM, Hilmar Lapp notifications@github.com wrote:

I think the manuscript needs some more work. I'm doing a first pass with comments, and then we can plan for a conference call.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-58058834.

Carl Boettiger UC Santa Cruz http://carlboettiger.info/

rvosa commented 9 years ago

I would be up for that as well.

On Tue, Oct 21, 2014 at 9:31 PM, Carl Boettiger notifications@github.com wrote:

Hey @hlapp just wanted to check in where we are on this. Time to schedule a chat?

Carl Boettiger http://carlboettiger.info

sent from mobile device; my apologies for any terseness or typos On Oct 6, 2014 10:54 AM, "Carl Boettiger" cboettig@gmail.com wrote:

@hlapp Sounds good, many thanks!

On Mon, Oct 6, 2014 at 10:53 AM, Hilmar Lapp notifications@github.com wrote:

I think the manuscript needs some more work. I'm doing a first pass with comments, and then we can plan for a conference call.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-58058834.

Carl Boettiger UC Santa Cruz http://carlboettiger.info/

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-59984538.

hlapp commented 9 years ago

I'm taking the text onto the plane to Stockholm (TDWG). Chat sounds great, but needs to be after Nov 3.

-hilmar

Sent from away

On Oct 21, 2014, at 3:31 PM, Carl Boettiger notifications@github.com wrote:

Hey @hlapp just wanted to check in where we are on this. Time to schedule a chat?

Carl Boettiger http://carlboettiger.info

sent from mobile device; my apologies for any terseness or typos On Oct 6, 2014 10:54 AM, "Carl Boettiger" cboettig@gmail.com wrote:

@hlapp Sounds good, many thanks!

On Mon, Oct 6, 2014 at 10:53 AM, Hilmar Lapp notifications@github.com wrote:

I think the manuscript needs some more work. I'm doing a first pass with comments, and then we can plan for a conference call.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-58058834.

Carl Boettiger UC Santa Cruz http://carlboettiger.info/

— Reply to this email directly or view it on GitHub.

cboettig commented 9 years ago

Sounds good, shall we schedule a Skype / google hangout / whatnot next week then?

Carl Boettiger http://carlboettiger.info

sent from mobile device; my apologies for any terseness or typos On Oct 23, 2014 10:53 AM, "Hilmar Lapp" notifications@github.com wrote:

I'm taking the text onto the plane to Stockholm (TDWG). Chat sounds great, but needs to be after Nov 3.

-hilmar

Sent from away

On Oct 21, 2014, at 3:31 PM, Carl Boettiger notifications@github.com wrote:

Hey @hlapp just wanted to check in where we are on this. Time to schedule a chat?

Carl Boettiger http://carlboettiger.info

sent from mobile device; my apologies for any terseness or typos On Oct 6, 2014 10:54 AM, "Carl Boettiger" cboettig@gmail.com wrote:

@hlapp Sounds good, many thanks!

On Mon, Oct 6, 2014 at 10:53 AM, Hilmar Lapp notifications@github.com

wrote:

I think the manuscript needs some more work. I'm doing a first pass with comments, and then we can plan for a conference call.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-58058834.

Carl Boettiger UC Santa Cruz http://carlboettiger.info/

— Reply to this email directly or view it on GitHub.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-60279460.

rvosa commented 9 years ago

Sounds good! I am fairly happy with google hangouts, and I have you in my circles. Ideally for me would be wednesday, when I'm not scheduled for anything (though I guess it would be evening for me anyway). I'd like to avoid Thursday evening and Friday.

On Thu, Oct 30, 2014 at 1:46 AM, Carl Boettiger notifications@github.com wrote:

Sounds good, shall we schedule a Skype / google hangout / whatnot next week then?

Carl Boettiger http://carlboettiger.info

sent from mobile device; my apologies for any terseness or typos On Oct 23, 2014 10:53 AM, "Hilmar Lapp" notifications@github.com wrote:

I'm taking the text onto the plane to Stockholm (TDWG). Chat sounds great, but needs to be after Nov 3.

-hilmar

Sent from away

On Oct 21, 2014, at 3:31 PM, Carl Boettiger notifications@github.com

wrote:

Hey @hlapp just wanted to check in where we are on this. Time to schedule a chat?

Carl Boettiger http://carlboettiger.info

sent from mobile device; my apologies for any terseness or typos On Oct 6, 2014 10:54 AM, "Carl Boettiger" cboettig@gmail.com wrote:

@hlapp Sounds good, many thanks!

On Mon, Oct 6, 2014 at 10:53 AM, Hilmar Lapp < notifications@github.com>

wrote:

I think the manuscript needs some more work. I'm doing a first pass with comments, and then we can plan for a conference call.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-58058834.

Carl Boettiger UC Santa Cruz http://carlboettiger.info/

— Reply to this email directly or view it on GitHub.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-60279460.

— Reply to this email directly or view it on GitHub https://github.com/ropensci/RNeXML/issues/79#issuecomment-61029801.

hlapp commented 9 years ago

I'm going to make the call that this is addressed, in part with PR #106.