Joss-reviews: [REVIEW]: Samewords: Word disambiguation in critical text editions

[whedon]

Submitting author: @Stenskjaer (Michael Stenskjær Christensen)
Repository: https://github.com/stenskjaer/samewords
Version: 0.5.6.
Editor: @Kevin-Mattheus-Moerman
Reviewers: @maieul, @Padlina
Archive: 10.5281/zenodo.2609228

Status

Status badge code:

HTML: <a href="http://joss.theoj.org/papers/2734f056707652e645a2ff9d76dcbeb9"><img src="http://joss.theoj.org/papers/2734f056707652e645a2ff9d76dcbeb9/status.svg"></a>
Markdown: [![status](http://joss.theoj.org/papers/2734f056707652e645a2ff9d76dcbeb9/status.svg)](http://joss.theoj.org/papers/2734f056707652e645a2ff9d76dcbeb9)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@maieul & @Padlina, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @Kevin-Mattheus-Moerman know.

✨ Please try and complete your review in the next two weeks ✨

Review checklist for @maieul

Conflict of interest

• [x] As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Version: 0.5.6.
• [x] Authorship: Has the submitting author (@Stenskjaer) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Authors: Does the paper.md file include a list of authors with their affiliations?
• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

---

Review checklist for @Padlina

Conflict of interest

• [x] As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Version: 0.5.6.
• [x] Authorship: Has the submitting author (@Stenskjaer) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Authors: Does the paper.md file include a list of authors with their affiliations?
• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @maieul, it looks like you're currently assigned as the reviewer for this paper :tada:.

:star: Important :star:

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

1. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[Kevin-Mattheus-Moerman]

@stenskjaer, @maieul, @MarjorieBurghart, and @Padlina this is where the review happens. There are tickboxes (and information) at the top of this issue which will guide you through the review process. You may also check out our review guidelines. Let me know if you have any questions.
You can comment on and discuss issue here. For larger discussions/issues you are encouraged to create issues on the project repository and refer to them here.
Let the reviewing begin! :rocket:

[Kevin-Mattheus-Moerman]

@maieul, @MarjorieBurghart, and @Padlina how are you getting on? Let me know if I can help with anything.

[maieul]

I will do test this week-end. But in any case, there is for a me a problem in the article about "A statement of need:". But I don't know if I need to evaluate, for this point, the software or the article.

[Kevin-Mattheus-Moerman]

Thanks @maieul. The statement of need is about the software of course but should be clearly present in both the paper and the documentation. If either of these do not clearly state what problems the software is designed to solve and who the target audience is, then please mention that here so the authors can work on adding these.

[maieul]

@stenskjaer

As mentionned earlier, I think that for a journal as floss, you must be more explicit about the problem your software deals, and present at least some information about what is a critical edition.

[Padlina]

@Kevin-Mattheus-Moerman Just to be sure that I'm testing everything needed: documentation is this and software paper is this, right? Should we also test the API interface and the web service?

[stenskjaer]

@Padlina It is my understanding that you should not test the API and web service, as it is an assistive or auxilliary way of using the software. At least that is my expectation. Comments are of course welcome.
@Kevin-Mattheus-Moerman may correct me, if I am wrong.

@maieul Thank you for the observation. I think it is a good point.

Also, @Kevin-Mattheus-Moerman, I think it is most meaningful that I make changes when all the reviews are done so I can get an overview of how to respond to the feedback. If you editors have good experience with other procedures, let me know.

[Padlina]

@stenskjaer I think that there is some issues with the sensitive context match. See stenskjaer/samewords/issues/36

[Kevin-Mattheus-Moerman]

@Padlina yes we can skip the API and web service for now. Focus on software functionality claimed/presented in the paper.

@stenskjaer in relation to waiting for all review comments to come in, I would recommend tackling issues one at a time as they come in. This way, I think, you are more likely to keep reviewers involved (we've had occasions where communication with reviewers dried up because the process took too long), and has so far been the smoothest approach. But, I leave this up to you, what ever you prefer.

[Kevin-Mattheus-Moerman]

@maieul, @MarjorieBurghart, @Padlina can you provide an update on where we stand in the review process? Has @stenskjaer worked on the issues you highlighted? Please tick as many boxes as you are currently able to at the top. Also please list any key issues you feel are preventing you from ticking the last boxes. Thanks.

[stenskjaer]

@Kevin-Mattheus-Moerman I have added some paragraphs to give the context suggested by @maieul and pushed it to the repo of the software. But I don't know if I should trigger a rebuild of the article from in here, or somewhere else?

Further, these changes (caused by the reviews under progress) has moved the history of the repo past the 0.5.0 release flag in the repo. Should it be updated or indicated that the HEAD of the submitted material is ahead of the version indicated in the description of this review?

[Kevin-Mattheus-Moerman]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[Kevin-Mattheus-Moerman]

@stenskjaer thanks for the update. You can call @whedon generate pdf here at any time to recreate the PDF.
In relation to the version number. That is fine. Thanks for letting us know. We will make sure we update the number if this work is accepted in JOSS.

[Kevin-Mattheus-Moerman]

@maieul can you check the updated paper? Thanks.

[maieul]

@stenskjaer thank. I think it is clear now.
@Kevin-Mattheus-Moerman I will pursue the peer-review process

[Kevin-Mattheus-Moerman]

Best wishes for 2019 everybody !

[Kevin-Mattheus-Moerman]

@maieul thanks for your work as reviewer so far. I noticed you have not ticked the functionality box. Can you elaborate what @stenskjaer can work on with regards to this point? Thanks

[Kevin-Mattheus-Moerman]

@Padlina can you give an update as to where we stand? I believe @stenskjaer worked on some of your comments. Thanks.

[maieul]

@Kevin-Mattheus-Moerman I juste need to write some MWE to test the feature.
I will try to do it soon

[Padlina]

@Kevin-Mattheus-Moerman I finished my review and ticked all the boxes. I also gave Michael some last small suggestions. Should I do something else to finish the review process?

[Kevin-Mattheus-Moerman]

@Padlina. Nope looks like you are done. Thanks!

[Kevin-Mattheus-Moerman]

@stenskjaer have you responded to @Padlina 's "small suggestions" (@Padlina can you link to where these suggestions are discussed?)?

[Kevin-Mattheus-Moerman]

@stenskjaer see my comment above :point_up: , any updates on responding to these points?

[Kevin-Mattheus-Moerman]

@stenskjaer see my comment above point_up , any updates on responding to these points?

Any updates on working on the points above?

[stenskjaer]

Thank you for your patience. I have received the following recommendations and feedback from @Padlina (thank you very much @Padlina, by the way!)

• [x] Providing a minimal working .tex example would be quite useful. [Added in the docs. This avoids making the paper longer than most necessary (which I get is the aim of the JOSS).]
• [x] https://samewords.readthedocs.io/en/latest/: in the example, the "for" word is green, but I don't see why [formatting updated]
• [x] https://s3.amazonaws.com/samewords-app/index.html give an error [update the url]
• [x] on page https://samewords.readthedocs.io/en/latest/configuration.html, the phrase "By default all characters that are not word characters, punctuation or \ { or } is considered part of a word." => it is not really clear which special characters are also considered part of a word. [Phrasing modified]
• [x] In the same page, "If you feel bold you could of course edit the punctuation list in the settings file". => specify which settings file [That sentence is not needed and has been removed]
• [x] I would provide an example of configuration settings for each parameter [I have added a reference to where the example configuration file can be found (in the root directory of the package and the online github repo with a link to https://github.com/stenskjaer/samewords/blob/master/sample_config.json)]
• [x] Under the section "multiword", the third paragraph ("A word with edtext{a word}{Afootnote{another D}} after it.") should be displayed as code [Actually it is all a text example to it is now a proper code block.]
• [x] Section "sensitive_context_match": "The value of the settings variable sensitive_proximity_match" => which one? sensitive_context_match or sensitive_proximity_match ? [Fixed, it should be sensitive_context_match]

I have pushed the updates to Github and changed the docs as described in the list above.

[Kevin-Mattheus-Moerman]

@maieul, @Padlina thanks for your review efforts!!! Can you confirm you are happy to accept this submission?

[Kevin-Mattheus-Moerman]

@MarjorieBurghart Are you still able to review this work? If so please complete the review at your earliest convenience. If I do not hear from you we will assume you are no longer able to review this work and we will proceed without your review.

[Kevin-Mattheus-Moerman]

@whedon check references

[whedon]

Attempting to check references...

[whedon]

```Reference check summary:

OK DOIs

• None

MISSING DOIs

• https://doi.org/10.5802/cg.282 may be missing for title: Reledmac: Typeset scholarly editions with LaTeX

INVALID DOIs

• None
  ```

[maieul]

ok for me

[Kevin-Mattheus-Moerman]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[maieul]

@Kevin-Mattheus-Moerman I could ask to ctan team to have DOI, but I am not sur that is pertinent, as ctan is stable in its url

[Kevin-Mattheus-Moerman]

I think it is okay to skip that DOI. @openjournals/joss-eics should @maieul list the package differently in the .bib file to avoid the missing DOI warning?

[danielskatz]

The missing DOI warning is just a warning. Just ignore it if it doesn't make sense.

[stenskjaer]

The article looks good to me. Is there anything I should do now?

[Padlina]

@Kevin-Mattheus-Moerman ok for me too

[Kevin-Mattheus-Moerman]

@whedon remove @MarjorieBurghart as reviewer

[whedon]

OK, @MarjorieBurghart is no longer a reviewer

[Kevin-Mattheus-Moerman]

Great. It looks like we are in good shape.

@stenskjaer can you please do the following:

• [x] Create an archived version of the software on a service like ZENODO (some have found these steps useful for automated archival of releases), and please list the DOI here once completed?

• [x] Can you tell us what the latest version (or release) tag is for the reviewed and archived software (it likely moved on from 0.5.0)?

Thanks.

[Kevin-Mattheus-Moerman]

@stenskjaer :wave: :point_up:

[stenskjaer]

Sorry for the wait!

• The Zenodo version is at https://zenodo.org/record/2609228 (DOI: 10.5281/zenodo.2609228)
• The version is 0.5.6.

[Kevin-Mattheus-Moerman]

@whedon set 10.5281/zenodo.2609228 as archive

[whedon]

OK. 10.5281/zenodo.2609228 is the archive.

[Kevin-Mattheus-Moerman]

@whedon set 0.5.6. as version

[whedon]

OK. 0.5.6. is the version.

[Kevin-Mattheus-Moerman]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

```Reference check summary:

OK DOIs

• 10.5281/zenodo.1306293 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[whedon]

Check final proof :point_right: https://github.com/openjournals/joss-papers/pull/609

If the paper PDF and Crossref deposit XML look good in https://github.com/openjournals/joss-papers/pull/609, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.
@whedon accept deposit=true

[Kevin-Mattheus-Moerman]

@openjournals/joss-eics I recommend this submission is accepted

[labarba]

@stenskjaer — Since we will have the Zenodo archive DOI on the front page of the paper, as part of the metadata shown in the margin note, we don't include a citation to it or mention it in the paper. Can you delete that?

[stenskjaer]

@labarba: Yep, that should be done now.

[labarba]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

```Reference check summary:

OK DOIs

• None

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[whedon]

Check final proof :point_right: https://github.com/openjournals/joss-papers/pull/621

If the paper PDF and Crossref deposit XML look good in https://github.com/openjournals/joss-papers/pull/621, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.
@whedon accept deposit=true

[labarba]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

1. Check final PDF and Crossref metadata that was deposited :point_right: https://github.com/openjournals/joss-papers/pull/622
2. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.00941
3. If everything looks good, then close this review issue.

4. Party like you just published a paper! 🎉🌈🦄💃👻🤘

   Any issues? notify your editorial technical team...

[labarba]

Congratulations, @stenskjaer, your JOSS paper is published!

Big thanks to our editor: @Kevin-Mattheus-Moerman, and the reviewers: @maieul, @Padlina — we couldn't do this without you! 🙏

[whedon]

:tada::tada::tada: Congratulations on your paper acceptance! :tada::tada::tada:

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](http://joss.theoj.org/papers/10.21105/joss.00941/status.svg)](https://doi.org/10.21105/joss.00941)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.00941">
  <img src="http://joss.theoj.org/papers/10.21105/joss.00941/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: http://joss.theoj.org/papers/10.21105/joss.00941/status.svg
   :target: https://doi.org/10.21105/joss.00941

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.salsalabs.org/donate-to-joss