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.
