[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: [RFR] templates://dokuwiki/{templates} (17 templates)



Tanguy Ortolo wrote:
> I would like to ask for review the following debconf templates for the
> dokuwiki package.

Okay; commentary below, patch and modified version attached, but I
suspect I'll need to revise it once Christian's had a look.

> Template: dokuwiki/system/configure-webserver
> Type: multiselect
> __Choices: apache2
> Default: apache2
> _Description: Web server(s) to configure automatically:
>  DokuWiki runs on any web server supporting PHP, however this
>  script is only able to configure Apache 2 automatically.

Optionally s/runs/can run/, but I left that out of my patch.

Comma-spliced "however" is deprecated, and this script shouldn't
really refer to itself (users don't want to know how debconf works):

   DokuWiki runs on any web server supporting PHP, but only Apache 2
   can be configured automatically.

>  .
>  Please select the web server(s) that should be configured
>  automatically for DokuWiki.

If this is a choice of either apache2 or nothing, why multiselect?
Just to leave room for expansion?  At present the fact it talks
about "web server(S)" is a bit confusing.
 
> Template: dokuwiki/system/restart-webserver
> Type: boolean
> Default: true
> _Description: Should the webserver(s) be restarted now?
                              ^
The recommended newbie-friendly spelling makes it two words.

>  In order to activate the new configuration, the reconfigured web
>  server(s) have to be restarted.

Giving optionally-plural "web server(s)" plural agreement ("have")
is legal but again confusing.
 
> Template: dokuwiki/system/documentroot
> Type: string
> _Description: Wiki location:
>  DokuWiki will be accessible through a directory of your website.
>  By default, this is http://yourserver/dokuwiki, but you can
>  change it to be anything within your server.  Enter just the directory
>  portion below.
> Default: /dokuwiki

If it's running on serverbox1.lan, even /proc is "within my server",
and I'm pretty sure I can't put it there - only below the webroot.
Also, no need to state the default, which is already there in the
text entry box... but is it guaranteed that it'll appear "below"?
How about just:

   Specify the directory below the server's docroot from which
   DokuWiki should be accessible.
 
> Template: dokuwiki/system/accessible
> Type: select
> _Description: Authorized network:
>  A Wiki is normally used to provide unlimited access to information, which
     ^
>  can be freely modified by anyone.  Since this is not always wanted, 
>  it is possible to restrict access to the site on the basis of the
>  originating IP address.

Wikipedia say lowercase "wiki".  Here's a more concise phrasing:

    Wikis normally provide open access to their content, allowing anyone
    to modify it. Alternatively, access can be restricted by IP address.
>  .
>  If you select 'localhost only', only people on the localhost (the machine
>  the Wiki is running on) will be able to connect.  'local network' will
>  allow people on machines in a local network (which you will need to
>  specify) to talk to the Wiki.  'global' will allow anyone, any where, to
>  connect to the Wiki.

We could avoid the initial lowercase by saying "Select 'foo' to
allow..." in each case, but never mind.  Apply the d-l-e house
style: doublequotes, singlespaced sentences.  And one-word
"anywhere". 

>  .
>  For security, this is set to 'localhost only' by default.  Unless you have
>  a particular need for privacy on your Wiki, you should be able to allow
>  access globally without compromising site security.

(Should?  All software "should" be secure.  I'm assuming this means
roughly "DokuWiki's security model is known to be reliable", so
please tone it down if that's too much to claim.)

   The default is for site security, but more permissive settings should
   be safe unless you have a particular need for privacy.

> __Choices: localhost only, local network, global
> Default: localhost only
> 
> Template: dokuwiki/system/localnet
> Type: string
> _Description: Local network:
>  The specification of your local network should either be
>  an IP network in CIDR format (x.x.x.x/y) or a domain specification (like
>  .mydomain.com).

mydomain.com exists!  Use example.org.

>  .
>  Anyone who matches the specification given below will be given full and
>  complete access to the DokuWiki.
> Default: 10.0.0.0/24

s/the specification given below/this specification/

s/the DokuWiki/Dokuwiki's content/ (they can't e.g. kill the process)

> Default: 10.0.0.0/24
> 
> Template: dokuwiki/system/purgepages
> Type: boolean
> _Description: Purge pages on package removal?
>  By default, DokuWiki stores all its pages in a file database in
>  /var/lib/dokuwiki.

(What's a "file database"?  Couldn't it just say "database"?)

>  .
>  Accepting this option will leave you with a tidier system when the
>  DokuWiki package is removed, but may cause information loss if you have an
>  operational Wiki that gets removed.
> Default: false
> 
> Template: dokuwiki/system/writeconf
> Type: boolean
> _Description: Make the configuration web-writeable?
>  DokuWiki includes a web-based configuration interface. To be usable, it
>  requires the web server to have writing permission to the configuration
>  directory.
>  .
>  Accepting this option will give the web server writing permissions on the
>  configuration directory and files.
>  .
>  The configuration files will still be readable and editable by hand
>  regardless whether you accept or not this option.

Oops, good until that last line:
   regardless of whether or not you accept this option.

And I suppose "writing permission" is usually "write permission".

> Default: false
> 
> Template: dokuwiki/system/writeplugins
> Type: boolean
> _Description: Make the plugins directory web-writeable?
>  DokuWiki includes a web-based plugin installation interface. To be useable,

For consistency, s/useable/usable/

>  it requires the web server to have writing permission to the plugins directory.
>  .
>  Accepting this option will give the web server writing permissions to the
>  plugins directory.
>  .
>  Plugins can still be installed by hand regardless whether you accept or not
>  this option.

Likewise "regardless of whether or not".

> Default: false
> 
> Template: dokuwiki/wiki/title
> Type: string
> _Description: Wiki title:
>  The Wiki title will be displayed in the upper right corner of the default
>  template and on the browser window title.
> Default: Debian DokuWiki
> 
> Template: dokuwiki/wiki/acl
> Type: boolean
> _Description: Enable ACL?
>  Enable this to use an Access Control List for restricting what the users of
>  your wiki may do.
>  .
>  This is a recommended setting because without ACL support you will not have
>  access to the administration features of DokuWiki.
> Default: true
> 
> Template: dokuwiki/wiki/superuser
> Type: string
> _Description: Administrator name:
>  This script can create an initial administrator account that will allow you to
>  create new wiki users and manage the wiki configuration. The username
>  should be lowercase and ASCII letters only. Spaces are not allowed here.
>  .
>  Leave this field blank if you do not want to create an administrator account
>  now.
> Default: admin

Eliminate "this script" again.  It seems odd that this takes the
time to prohibit usernames like "the management" when "ASCII
letters" already excludes spaces; how about "the_management"?  Is
that prohibited too? 

Reshuffling:
  _Description: Administrator username:
   Please enter a name for the administrator account, which will be able to
   manage DokuWiki's configuration and create new wiki users. The username
   should be composed of lowercase ASCII letters only.
   .
   If this field is left blank, no administrator account will be created now.

(Or if it really means "lowercase ASCII characters", it should say
that.) 
 
> Template: dokuwiki/wiki/fullname
> Type: string
> _Description: Administrator real name:
> Default: DokuWiki Administrator
>  Please enter the full name associated to the wiki administrator account.
>  This name will be stored in the wiki password file as an informative
>  field, and will be displayed with the wiki page changes made from the
>  administrator account.

s/associated to/associated with/, s/made from/made by/

> 
> Template: dokuwiki/wiki/email
> Type: string
> _Description: Administrator email address:
>  Please enter the email address associated to the wiki administrator account.
>  This address will be stored in the wiki password file, and may be used
>  to get a new password if you loose the original administrator password.
> Default: webmaster@localhost

Ditto, plus an English orthography gotcha: s/loose/lose/.

Oh, and to cut down on repeats I'll rephrase it:
   to get a new administrator password if you lose the original.

> Template: dokuwiki/wiki/password
> Type: password
> _Description: Administrator password:
>  Please choose a password for the wiki administrator.
> 
> Template: dokuwiki/wiki/confirm
> Type: password
> _Description: Password confirmation:
>  Please enter the same password again to verify
>  you have typed it correctly.
> 
> Template: dokuwiki/wiki/failpass
> Type: error
> _Description: Password confimation failed!
>  The passwords do not match, please type them again.

Comma splice - make it two sentences.

> 
> Template: dokuwiki/wiki/policy
> Type: select
> _Description: Initial ACL policy?

s/?/:/ for non-booleans.

>  The installer will set up an initial ACL configuration for you. What you
>  choose here depends on how you intend to use the Wiki.

Don't mention the installer.

>  .
>  An open wiki is available to anonymous users for reading and writing.
>  A public wiki is available to anonymous users for reading, but limited to
>  registered users for writing. A closed wiki is only accessible to registered
>  users for both reading and writing.

Wait; if "open", "public", and "closed" are untranslatable verbatim
strings, are we allowed to integrate the words into the text like
this?  Maybe it should go to the opposite extreme:
   
   Please select what initial ACL configuration should be set up to match
   the intended usage of this wiki:
    "open":   both readable and writeable for anonymous users;
    "public": readable for anonymous users, writeable for registered users;
    "closed": readable and writeable for registered users only.

>  .
>  This is only an initial setup, you will be able to adjust the ACL rules later.

Paper over the comma splice: s/,/;/
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
--- templates.orig	2010-03-13 13:01:59.000000000 +0000
+++ templates	2010-03-13 14:35:28.000000000 +0000
@@ -3,8 +3,8 @@
 __Choices: apache2
 Default: apache2
 _Description: Web server(s) to configure automatically:
- DokuWiki runs on any web server supporting PHP, however this
- script is only able to configure Apache 2 automatically.
+ DokuWiki runs on any web server supporting PHP, but only Apache 2
+ can be configured automatically.
  .
  Please select the web server(s) that should be configured
  automatically for DokuWiki.
@@ -12,36 +12,31 @@
 Template: dokuwiki/system/restart-webserver
 Type: boolean
 Default: true
-_Description: Should the webserver(s) be restarted now?
+_Description: Should the web server(s) be restarted now?
  In order to activate the new configuration, the reconfigured web
  server(s) have to be restarted.
 
 Template: dokuwiki/system/documentroot
 Type: string
 _Description: Wiki location:
- DokuWiki will be accessible through a directory of your website.
- By default, this is http://yourserver/dokuwiki, but you can
- change it to be anything within your server.  Enter just the directory
- portion below.
+ Specify the directory below the server's docroot from which
+ DokuWiki should be accessible.         
 Default: /dokuwiki
 
 Template: dokuwiki/system/accessible
 Type: select
 _Description: Authorized network:
- A Wiki is normally used to provide unlimited access to information, which
- can be freely modified by anyone.  Since this is not always wanted, 
- it is possible to restrict access to the site on the basis of the
- originating IP address.
+ Wikis normally provide open access to their content, allowing anyone
+ to modify it. Alternatively, access can be restricted by IP address.
  .
- If you select 'localhost only', only people on the localhost (the machine
- the Wiki is running on) will be able to connect.  'local network' will
+ If you select "localhost only", only people on the localhost (the machine
+ the wiki is running on) will be able to connect. "local network" will
  allow people on machines in a local network (which you will need to
- specify) to talk to the Wiki.  'global' will allow anyone, any where, to
- connect to the Wiki.
+ specify) to talk to the wiki. "global" will allow anyone, anywhere, to
+ connect to the wiki.
  .
- For security, this is set to 'localhost only' by default.  Unless you have
- a particular need for privacy on your Wiki, you should be able to allow
- access globally without compromising site security.
+ The default is for site security, but more permissive settings should
+ be safe unless you have a particular need for privacy.
 __Choices: localhost only, local network, global
 Default: localhost only
 
@@ -50,54 +45,54 @@
 _Description: Local network:
  The specification of your local network should either be
  an IP network in CIDR format (x.x.x.x/y) or a domain specification (like
- .mydomain.com).
+ .example.org).
  .
- Anyone who matches the specification given below will be given full and
- complete access to the DokuWiki.
+ Anyone who matches this specification will be given full and complete
+  access to DokuWiki's content.
 Default: 10.0.0.0/24
 
 Template: dokuwiki/system/purgepages
 Type: boolean
-_Description: Purge pages on package removal?
+_Description: Purge pages on package 
  By default, DokuWiki stores all its pages in a file database in
  /var/lib/dokuwiki.
  .
  Accepting this option will leave you with a tidier system when the
  DokuWiki package is removed, but may cause information loss if you have an
- operational Wiki that gets removed.
+ operational wiki that gets removed.
 Default: false
 
 Template: dokuwiki/system/writeconf
 Type: boolean
 _Description: Make the configuration web-writeable?
  DokuWiki includes a web-based configuration interface. To be usable, it
- requires the web server to have writing permission to the configuration
+ requires the web server to have write permission to the configuration
  directory.
  .
- Accepting this option will give the web server writing permissions on the
+ Accepting this option will give the web server write permissions on the
  configuration directory and files.
  .
  The configuration files will still be readable and editable by hand
- regardless whether you accept or not this option.
+ regardless of whether or not you accept this option.
 Default: false
 
 Template: dokuwiki/system/writeplugins
 Type: boolean
 _Description: Make the plugins directory web-writeable?
- DokuWiki includes a web-based plugin installation interface. To be useable,
- it requires the web server to have writing permission to the plugins directory.
+ DokuWiki includes a web-based plugin installation interface. To be usable,
+ it requires the web server to have write permission to the plugins directory.
  .
- Accepting this option will give the web server writing permissions to the
+ Accepting this option will give the web server write permissions to the
  plugins directory.
  .
- Plugins can still be installed by hand regardless whether you accept or not
- this option.
+ Plugins can still be installed by hand regardless of whether or not you
+ accept this option.
 Default: false
 
 Template: dokuwiki/wiki/title
 Type: string
-_Description: Wiki title:
- The Wiki title will be displayed in the upper right corner of the default
+_Description: wiki title:
+ The wiki title will be displayed in the upper right corner of the default
  template and on the browser window title.
 Default: Debian DokuWiki
 
@@ -113,30 +108,29 @@
 
 Template: dokuwiki/wiki/superuser
 Type: string
-_Description: Administrator name:
- This script can create an initial administrator account that will allow you to
- create new wiki users and manage the wiki configuration. The username
- should be lowercase and ASCII letters only. Spaces are not allowed here.
+_Description: Administrator username:
+ Please enter a name for the administrator account, which will be able to
+ manage DokuWiki's configuration and create new wiki users. The username
+ should be composed of lowercase ASCII letters only.
  .
- Leave this field blank if you do not want to create an administrator account
- now.
+ If this field is left blank, no administrator account will be created now.
 Default: admin
 
 Template: dokuwiki/wiki/fullname
 Type: string
 _Description: Administrator real name:
 Default: DokuWiki Administrator
- Please enter the full name associated to the wiki administrator account.
+ Please enter the full name associated with the wiki administrator account.
  This name will be stored in the wiki password file as an informative
- field, and will be displayed with the wiki page changes made from the
+ field, and will be displayed with the wiki page changes made by the
  administrator account.
 
 Template: dokuwiki/wiki/email
 Type: string
 _Description: Administrator email address:
- Please enter the email address associated to the wiki administrator account.
+ Please enter the email address associated with the wiki administrator account.
  This address will be stored in the wiki password file, and may be used
- to get a new password if you loose the original administrator password.
+ to get a new administrator password if you lose the original.
 Default: webmaster@localhost
 
 Template: dokuwiki/wiki/password
@@ -153,19 +147,17 @@
 Template: dokuwiki/wiki/failpass
 Type: error
 _Description: Password confimation failed!
- The passwords do not match, please type them again.
+ The passwords do not match. Please type them again.
 
 Template: dokuwiki/wiki/policy
 Type: select
-_Description: Initial ACL policy?
- The installer will set up an initial ACL configuration for you. What you
- choose here depends on how you intend to use the Wiki.
- .
- An open wiki is available to anonymous users for reading and writing.
- A public wiki is available to anonymous users for reading, but limited to
- registered users for writing. A closed wiki is only accessible to registered
- users for both reading and writing.
+_Description: Initial ACL policy:
+ Please select what initial ACL configuration should be set up to match
+ the intended usage of this wiki:
+  "open":   both readable and writeable for anonymous users;
+  "public": readable for anonymous users, writeable for registered users;
+  "closed": readable and writeable for registered users only.
  .
- This is only an initial setup, you will be able to adjust the ACL rules later.
+ This is only an initial setup; you will be able to adjust the ACL rules later.
 __Choices: open, public, closed
 Default: public
Template: dokuwiki/system/configure-webserver
Type: multiselect
__Choices: apache2
Default: apache2
_Description: Web server(s) to configure automatically:
 DokuWiki runs on any web server supporting PHP, but only Apache 2
 can be configured automatically.
 .
 Please select the web server(s) that should be configured
 automatically for DokuWiki.

Template: dokuwiki/system/restart-webserver
Type: boolean
Default: true
_Description: Should the web server(s) be restarted now?
 In order to activate the new configuration, the reconfigured web
 server(s) have to be restarted.

Template: dokuwiki/system/documentroot
Type: string
_Description: Wiki location:
 Specify the directory below the server's docroot from which
 DokuWiki should be accessible.         
Default: /dokuwiki

Template: dokuwiki/system/accessible
Type: select
_Description: Authorized network:
 Wikis normally provide open access to their content, allowing anyone
 to modify it. Alternatively, access can be restricted by IP address.
 .
 If you select "localhost only", only people on the localhost (the machine
 the wiki is running on) will be able to connect. "local network" will
 allow people on machines in a local network (which you will need to
 specify) to talk to the wiki. "global" will allow anyone, anywhere, to
 connect to the wiki.
 .
 The default is for site security, but more permissive settings should
 be safe unless you have a particular need for privacy.
__Choices: localhost only, local network, global
Default: localhost only

Template: dokuwiki/system/localnet
Type: string
_Description: Local network:
 The specification of your local network should either be
 an IP network in CIDR format (x.x.x.x/y) or a domain specification (like
 .example.org).
 .
 Anyone who matches this specification will be given full and complete
  access to DokuWiki's content.
Default: 10.0.0.0/24

Template: dokuwiki/system/purgepages
Type: boolean
_Description: Purge pages on package 
 By default, DokuWiki stores all its pages in a file database in
 /var/lib/dokuwiki.
 .
 Accepting this option will leave you with a tidier system when the
 DokuWiki package is removed, but may cause information loss if you have an
 operational wiki that gets removed.
Default: false

Template: dokuwiki/system/writeconf
Type: boolean
_Description: Make the configuration web-writeable?
 DokuWiki includes a web-based configuration interface. To be usable, it
 requires the web server to have write permission to the configuration
 directory.
 .
 Accepting this option will give the web server write permissions on the
 configuration directory and files.
 .
 The configuration files will still be readable and editable by hand
 regardless of whether or not you accept this option.
Default: false

Template: dokuwiki/system/writeplugins
Type: boolean
_Description: Make the plugins directory web-writeable?
 DokuWiki includes a web-based plugin installation interface. To be usable,
 it requires the web server to have write permission to the plugins directory.
 .
 Accepting this option will give the web server write permissions to the
 plugins directory.
 .
 Plugins can still be installed by hand regardless of whether or not you
 accept this option.
Default: false

Template: dokuwiki/wiki/title
Type: string
_Description: wiki title:
 The wiki title will be displayed in the upper right corner of the default
 template and on the browser window title.
Default: Debian DokuWiki

Template: dokuwiki/wiki/acl
Type: boolean
_Description: Enable ACL?
 Enable this to use an Access Control List for restricting what the users of
 your wiki may do.
 .
 This is a recommended setting because without ACL support you will not have
 access to the administration features of DokuWiki.
Default: true

Template: dokuwiki/wiki/superuser
Type: string
_Description: Administrator username:
 Please enter a name for the administrator account, which will be able to
 manage DokuWiki's configuration and create new wiki users. The username
 should be composed of lowercase ASCII letters only.
 .
 If this field is left blank, no administrator account will be created now.
Default: admin

Template: dokuwiki/wiki/fullname
Type: string
_Description: Administrator real name:
Default: DokuWiki Administrator
 Please enter the full name associated with the wiki administrator account.
 This name will be stored in the wiki password file as an informative
 field, and will be displayed with the wiki page changes made by the
 administrator account.

Template: dokuwiki/wiki/email
Type: string
_Description: Administrator email address:
 Please enter the email address associated with the wiki administrator account.
 This address will be stored in the wiki password file, and may be used
 to get a new administrator password if you lose the original.
Default: webmaster@localhost

Template: dokuwiki/wiki/password
Type: password
_Description: Administrator password:
 Please choose a password for the wiki administrator.

Template: dokuwiki/wiki/confirm
Type: password
_Description: Password confirmation:
 Please enter the same password again to verify
 you have typed it correctly.

Template: dokuwiki/wiki/failpass
Type: error
_Description: Password confimation failed!
 The passwords do not match. Please type them again.

Template: dokuwiki/wiki/policy
Type: select
_Description: Initial ACL policy:
 Please select what initial ACL configuration should be set up to match
 the intended usage of this wiki:
  "open":   both readable and writeable for anonymous users;
  "public": readable for anonymous users, writeable for registered users;
  "closed": readable and writeable for registered users only.
 .
 This is only an initial setup; you will be able to adjust the ACL rules later.
__Choices: open, public, closed
Default: public

Reply to: