Re: Review of debconf template for jalview
Pierre Gruet wrote:
> I have written the debconf template of the package jalview; could you please
> give me your opinion and possible suggestions for improvement if time
> permits?
>
> The template can be found at
> https://salsa.debian.org/java-team/jalview/-/blob/master/debian/po/templates.pot
> or is also below.
That isn't the debconf template, it's the potfile. It's easier to
work from the original templates file, so I'll fetch that.
Looking at the package description for some context I can see a couple
of problems with that, too. Mainly just that it assumes "alignment"
(in a "science" package) must be talking about biology - it might be
referring to geological alignments! So there should be at least one
mention of "genetic or protein sequence alignments", or whatever it is
that it's talking about exactly.
Also, there's a possible missing plural ending (it's hard to be sure)
and a surplus space before the final exclamation mark!
> Template: jalview/identifiersservice
> Type: boolean
> Default: true
> # Translators: "identifiers" or "accessions" are short tokens that may be
> # downloaded from identifiers.org to easily access some biological databases.
> # A bit more info at identifiers.org if needed.
> _Description: Allow downloading identifiers automatically from www.jalview.org?
Best Practices says to try to keep it to 50 characters, so I'm on the
lookout for ways of shortening this. And the word "allow" is an easy
target - it isn't quite right here, since asaying "no" won't disallow
it. Maybe for this and later cases you could just say:
_Description: Automatically download identifiers from jalview.org?
> Jalview can automatically download a list of identifiers.org URL templates
> for viewing accessions from various biological databases.
(Right, I understand "identifiers"... I'm slightly confused by "a list
of identifiers.org URL templates"... but if they're things I can use
for this moderately intelligible purpose it probably doesn't matter.)
> .
> This is a convenience for users but can be deactivated as it causes an
> automatic ping to www.jalview.org/services/identifiers, which records usage
> statistics.
> .
> Users can only override this preference from their own configuration file.
So they can't override it from... somebody else's configuration file?
Ah, coming back to this from later templates I deduce that the "only"
is here because it *can't* be done via the GUI. That's confusing if
I'm reading them in this order. Make it:
Individual users can override this setting in their configuration file.
>
> Template: jalview/news
> Type: boolean
> Default: true
> _Description: Allow automatic display of news from the Jalview website?
_Description: Automatically display news from jalview.org?
> Users will be automatically shown updates from
> https://www.jalview.org/feeds/desktop/rss in a popup window.
Just for consistency, don't assume this is set to true:
Jalview can automatically show users updates from
https://www.jalview.org/feeds/desktop/rss in a popup window.
> .
> The news feed is informative to users but its retrieval pings www.jalview.org,
> which records usage statistics.
> .
> If this is disabled, users may still manually open the news reader.
> Users can also override this preference in the Preferences window or from their
> own configuration file.
Oh, right (goes back to previous template...)
> Template: jalview/questionnaire
> Type: boolean
> Default: true
> _Description: Allow prompts from Jalview's website about a user questionnaire?
Okay, this is more like "allowing", in that Jalview seems to be trying
to do things that are getting a bit spammy. Still, it's too long, and
keeping it consistent also has the advantage of shortening it:
_Description: Automatically check for questionnaires from jalview.org?
> User questionnaires are posted from time to time on www.jalview.org, and
> Jalview can automatically query the site to look for them on startup, in order
> to prompt users to complete them.
I suppose this could be
Jalview can automatically query www.jalview.org on startup for the user
questionnaires that are posted on the site from time to time, and prompt
users to complete them
But it's not really an improvement - I'll leave it as it is.
> .
> Logs for the questionnaire service are used to record usage statistics, and
> anonymised cookies are stored in the user's preferences to track whether they
> have completed the latest questionnaire.
> .
> Users can enable or disable this query from their own configuration file, or
> from the Preferences window in the application.
When SF writers warned about a dystopian future of being tracked by
DNA databases I never thought it would be like this.
> Template: jalview/jws2services
> Type: boolean
> Default: true
> # Translators: web services are tools for analysis that are located on web
> # servers in order to bring more functionality compared to the standalone
> # software. "discovering" them corresponds to seeing what services are
> # available.
> # The sentence beginning with "Otherwise" means the users can do this discovery
> # from the menu of the software if the administrator has disabled it.
> _Description: Allow discovery of alignment and analysis web services at startup?
This one definitely needs to be shorter. The JABAWS website
expands the acronym (in its pagetitle) as "Java Bioinformatics
Analyses Web Services" - we could easily fit this much here and the
rest can go in the long description if we really need it:
_Description: Automatically discover JABA Web Services?
> The JABAWS system (www.compbio.dundee.ac.uk/jabaws) provides access to a range
> of third party multiple sequence alignment and analysis tools as web services.
> .
> Jalview can automatically query the public (or any other configured) JABAWS
> services on start-up. Otherwise, users will need to initiate discovery with a
> menu option.
> .
> Users can enable or disable startup discovery from their own configuration
> file or from the Preferences window in the application.
Hmm. Okay. Oh, except that we were spelling it "startup".
> Template: jalview/htmltemplates
> Type: boolean
> Default: true
> _Description: Allow downloading HTML templates automatically from Github?
As usual it's about whether it's automatic, not whether it's allowed:
_Description: Automatically download HTML templates from Github?
> Jalview automatically downloads the latest 'BioJS' HTML export template from
> https://github.com/jalview/exporter-templates on startup.
Jalview can automatically download the latest "BioJS" HTML export template from
https://github.com/jalview/exporter-templates on startup.
It's not obvious why I'd want this when the latest ones are six years
old, but okay. Presumably the reason this is configurable is that I
might not want github to be able to track what I'm doing - something
like:
.
This is a convenience for users but can be deactivated as it causes an
automatic ping to Github.
> .
> Users can only enable or disable this feature from their own configuration
> file.
Individual users can override this setting in their configuration file.
Okay, modified version and diff attached.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Template: jalview/identifiersservice
Type: boolean
Default: true
# Translators: "identifiers" or "accessions" are short tokens that may be
# downloaded from identifiers.org to easily access some biological databases.
# A bit more info at identifiers.org if needed.
_Description: Automatically download identifiers from jalview.org?
Jalview can automatically download a list of identifiers.org URL templates
for viewing accessions from various biological databases.
.
This is a convenience for users but can be deactivated as it causes an
automatic ping to www.jalview.org/services/identifiers, which records usage
statistics.
.
Individual users can override this setting in their configuration file.
Template: jalview/news
Type: boolean
Default: true
_Description: Automatically display news from jalview.org?
Jalview can automatically show updates from
https://www.jalview.org/feeds/desktop/rss in a popup window.
.
The news feed is informative to users but its retrieval pings www.jalview.org,
which records usage statistics.
.
If this is disabled, users may still manually open the news reader.
Users can also override this preference in the Preferences window or from their
own configuration file.
Template: jalview/questionnaire
Type: boolean
Default: true
_Description: Automatically check for questionnaires from jalview.org?
User questionnaires are posted from time to time on www.jalview.org, and
Jalview can automatically query the site to look for them on startup, in order
to prompt users to complete them.
.
Logs for the questionnaire service are used to record usage statistics, and
anonymised cookies are stored in the user's preferences to track whether they
have completed the latest questionnaire.
.
Users can enable or disable this query from their own configuration file, or
from the Preferences window in the application.
Template: jalview/jws2services
Type: boolean
Default: true
# Translators: web services are tools for analysis that are located on web
# servers in order to bring more functionality compared to the standalone
# software. "discovering" them corresponds to seeing what services are
# available.
# The sentence beginning with "Otherwise" means the users can do this discovery
# from the menu of the software if the administrator has disabled it.
_Description: Automatically discover JABA Web Services?
The JABAWS system (www.compbio.dundee.ac.uk/jabaws) provides access to a range
of third party multiple sequence alignment and analysis tools as web services.
.
Jalview can automatically query the public (or any other configured) JABAWS
services on startup. Otherwise, users will need to initiate discovery with a
menu option.
.
Users can enable or disable startup discovery from their own configuration
file or from the Preferences window in the application.
Template: jalview/htmltemplates
Type: boolean
Default: true
_Description: Automatically download HTML templates from Github?
Jalview cam automatically download the latest "BioJS" HTML export template
from https://github.com/jalview/exporter-templates on startup.
.
This is a convenience for users but can be deactivated as it causes an
automatic ping to Github.
.
Individual users can override this setting in their configuration file.
--- templates.old 2021-02-27 14:01:41.382078967 +0000
+++ templates.new 2021-02-27 16:04:24.433633460 +0000
@@ -4,7 +4,7 @@
# Translators: "identifiers" or "accessions" are short tokens that may be
# downloaded from identifiers.org to easily access some biological databases.
# A bit more info at identifiers.org if needed.
-_Description: Allow downloading identifiers automatically from www.jalview.org?
+_Description: Automatically download identifiers from jalview.org?
Jalview can automatically download a list of identifiers.org URL templates
for viewing accessions from various biological databases.
.
@@ -12,13 +12,13 @@
automatic ping to www.jalview.org/services/identifiers, which records usage
statistics.
.
- Users can only override this preference from their own configuration file.
+ Individual users can override this setting in their configuration file.
Template: jalview/news
Type: boolean
Default: true
-_Description: Allow automatic display of news from the Jalview website?
- Users will be automatically shown updates from
+_Description: Automatically display news from jalview.org?
+ Jalview can automatically show updates from
https://www.jalview.org/feeds/desktop/rss in a popup window.
.
The news feed is informative to users but its retrieval pings www.jalview.org,
@@ -31,7 +31,7 @@
Template: jalview/questionnaire
Type: boolean
Default: true
-_Description: Allow prompts from Jalview's website about a user questionnaire?
+_Description: Automatically check for questionnaires from jalview.org?
User questionnaires are posted from time to time on www.jalview.org, and
Jalview can automatically query the site to look for them on startup, in order
to prompt users to complete them.
@@ -52,12 +52,12 @@
# available.
# The sentence beginning with "Otherwise" means the users can do this discovery
# from the menu of the software if the administrator has disabled it.
-_Description: Allow discovery of alignment and analysis web services at startup?
+_Description: Automatically discover JABA Web Services?
The JABAWS system (www.compbio.dundee.ac.uk/jabaws) provides access to a range
of third party multiple sequence alignment and analysis tools as web services.
.
Jalview can automatically query the public (or any other configured) JABAWS
- services on start-up. Otherwise, users will need to initiate discovery with a
+ services on startup. Otherwise, users will need to initiate discovery with a
menu option.
.
Users can enable or disable startup discovery from their own configuration
@@ -66,9 +66,11 @@
Template: jalview/htmltemplates
Type: boolean
Default: true
-_Description: Allow downloading HTML templates automatically from Github?
- Jalview automatically downloads the latest 'BioJS' HTML export template from
- https://github.com/jalview/exporter-templates on startup.
+_Description: Automatically download HTML templates from Github?
+ Jalview cam automatically download the latest "BioJS" HTML export template
+ from https://github.com/jalview/exporter-templates on startup.
.
- Users can only enable or disable this feature from their own configuration
- file.
+ This is a convenience for users but can be deactivated as it causes an
+ automatic ping to Github.
+ .
+ Individual users can override this setting in their configuration file.
Reply to: