[request-tracker-maintainers] [RFR] templates://rtfm/{templates}

Justin B Rye jbr at edlug.org.uk
Mon Oct 22 22:01:06 UTC 2007 

Christian Perrier wrote:
> Your review should be sent as an answer to this mail.

I know the templates might get revised, but I'd already done the
work.

[...]
> + Please check the /usr/share/doc/rtfm/README.Debian file for more details.
> 
> Avoid the "if you want" style and just be factual.
> 
> Make a longer sentence than just "See README.Debian"

The name of the package (and therefore the doc directory) has
changed to rt3.6-rtfm. 
  
> - You can either retry, abort the installation or ignore the error. If you
> - want to retry, another attempt will be made at performing the operation.
> - If you abort, the operation will fail and you will need to downgrade,
> - reinstall, reconfigure the package, or otherwise manually intervene to
> - continue using it.  If you choose to ignore the error, the operation will
> + You can either retry the modification, abort the installation or ignore the error.

"Either" implies two options.  Not universally, but enough to trip
up readers when they run into the third; so just drop it.

> + If you abort the instalaltion, the operation will fail and you will need to downgrade,
> + reinstall, reconfigure the package, or manually apply the needed changes
> + to continue using RTFM. If you choose to ignore the error, the upgrade process will
>   continue.

s/instalaltion/installation/, as has been mentioned.

How do you downgrade, other than by purging and reinstalling?  I'm
not 100% sure I know what "reconfigure" means here either.
 
> Rephrase. Can be enhanced, still, imho.

Simplifying (and hoping it still makes sense):

  You can retry the modification, abort the installation or ignore the error.
  If you abort the installation, the operation will fail and you will need to
  manually intervene (for instance by purging and reinstalling). If you choose
  to ignore the error, the upgrade process will continue.

> - RTFM is an enterprise-grade knowledge management tool that enables an
> + RTFM is an knowledge management tool that enables an
> 
> "enterprise-grade" sounds like advertising.

That's "*a* knowledge management tool".

  Just as you use RT (Request Tracker, the open-source ticketing system) to log
  tickets and resolve issues, RTFM lets you open, categorize and search for
  "articles." Like RT, RTFM lets users contribute additional information

I'd prefer to standardise on "logical quotation", with punctuation
outside the quote marks unless it's part of the quote (and I suppose
I should make it single-quotes too):

  'articles'.

Then it says:

  RTFM is implemented as an add-on to RT. This package integrates with
  RT 3.6, available in the request-tracker3.6 package.        

...which seems a bit pointless, since the RT dependency is handled
automatically.  But the bit about RTFM being an RT add-on deserves
to be promoted to the first paragraph:

  RTFM is a knowledge management tool implemented as an add-on to RT that
  enables an organization to easily capture and share its employees'
  knowledge and wisdom.
-- 
JBR
Ankh kak! (Ancient Egyptian blessing)
-------------- next part --------------
--- ../rtfm.old/debian/templates	2007-10-19 07:13:17.000000000 +0100
+++ debian/templates	2007-10-22 20:21:43.000000000 +0100
@@ -1,34 +1,37 @@
 Template: rt3.6-rtfm/modify-database-permission
 Type: select
-_Choices: allow, prompt, deny
+__Choices: allow, prompt, deny
 Default: allow
 _Description: Permission to modify the database:
- RTFM needs some database modifications to be functional.  If you want, the
- installation procedure can make these modifications automatically or
- prompt you when they are needed. Alternatively, you can run the necessary
- commands manually. See README.Debian.
+ RTFM needs some database modifications to be functional. These
+ modifications can be made automatically or
+ you may be prompted when they are needed. Alternatively, you can run the necessary
+ commands manually.
+ .
+ Please check the /usr/share/doc/rt3.6-rtfm/README.Debian file for more details.
 
 Template: rt3.6-rtfm/modify-database-prompt
 Type: boolean
 Default: true
+#flag:translate!:3
 _Description: Modify the database?
- It looks like RTFM needs a database modification to be functional: ${modification}.
+ A database modification is required for RTFM to be functional:
+ .
+ ${modification}
 
 Template: rt3.6-rtfm/modify-database-error
 Type: select
-_Choices: abort, retry, ignore
+__Choices: abort, retry, ignore
 Default: abort
-_Description: Error modifying the database. Solution:
- An error seems to have occurred while modifying the database. If it's of
- any help, this was the error encountered:
+#flag:translate!:3
+_Description: Action after database modification error:
+ An error occurred while modifying the database:
  .
  ${error}
  .
  The full output should be available in the RT log, most probably syslog.
  .
- You can either retry, abort the installation or ignore the error. If you
- want to retry, another attempt will be made at performing the operation.
- If you abort, the operation will fail and you will need to downgrade,
- reinstall, reconfigure the package, or otherwise manually intervene to
- continue using it.  If you choose to ignore the error, the operation will
- continue.
+ You can retry the modification, abort the installation or ignore the error.
+ If you abort the installation, the operation will fail and you will need to
+ manually intervene (for instance by purging and reinstalling). If you choose
+ to ignore the error, the upgrade process will continue.
--- ../rtfm.old/debian/control	2007-10-19 07:13:17.000000000 +0100
+++ debian/control	2007-10-22 20:17:22.000000000 +0100
@@ -13,15 +13,13 @@
  libyaml-perl, libtree-simple-perl, ${misc:Depends}, ${perl:Depends}, 
  debconf | debconf-2.0, ucf (>= 0.28)
 Description: RT FAQ Manager
- RTFM is an enterprise-grade knowledge management tool that enables an
- organization to easily capture and share its employees' knowledge and wisdom.
+ RTFM is a knowledge management tool implemented as an add-on to RT that
+ enables an organization to easily capture and share its employees'
+ knowledge and wisdom.
  .
  Just as you use RT (Request Tracker, the open-source ticketing system) to log
  tickets and resolve issues, RTFM lets you open, categorize and search for
- "articles." Like RT, RTFM lets your users contribute additional information
- to existing articles and makes sure that each article's full history is
- preserved for future inspection. RTFM makes it easy to quickly search the
- knowledge base and find critical information.
- .
- RTFM is implemented as an add-on to RT. This package integrates with
- RT 3.6, available in the request-tracker3.6 package.
+ 'articles'. Like RT, RTFM lets users contribute additional information
+ to existing articles. It guarantees that each article's full history is
+ preserved for future inspection. RTFM simplifies browsing in the
+ knowledge base and finding critical information.
-------------- next part --------------
Template: rt3.6-rtfm/modify-database-permission
Type: select
__Choices: allow, prompt, deny
Default: allow
_Description: Permission to modify the database:
 RTFM needs some database modifications to be functional. These
 modifications can be made automatically or
 you may be prompted when they are needed. Alternatively, you can run the necessary
 commands manually.
 .
 Please check the /usr/share/doc/rt3.6-rtfm/README.Debian file for more details.

Template: rt3.6-rtfm/modify-database-prompt
Type: boolean
Default: true
#flag:translate!:3
_Description: Modify the database?
 A database modification is required for RTFM to be functional:
 .
 ${modification}

Template: rt3.6-rtfm/modify-database-error
Type: select
__Choices: abort, retry, ignore
Default: abort
#flag:translate!:3
_Description: Action after database modification error:
 An error occurred while modifying the database:
 .
 ${error}
 .
 The full output should be available in the RT log, most probably syslog.
 .
 You can retry the modification, abort the installation or ignore the error.
 If you abort the installation, the operation will fail and you will need to
 manually intervene (for instance by purging and reinstalling). If you choose
 to ignore the error, the upgrade process will continue.
-------------- next part --------------
Source: rtfm
Section: misc
Priority: optional
Maintainer: Debian Request Tracker Group <pkg-request-tracker-maintainers at lists.alioth.debian.org>
Uploaders: Niko Tyni <ntyni at iki.fi>
Build-Depends: quilt (>= 0.40-1), debhelper (>= 5)
Build-Depends-Indep: perl (>= 5.8.3), po-debconf
Standards-Version: 3.7.2.0

Package: rt3.6-rtfm
Architecture: all
Depends: request-tracker3.6, libhtml-tree-perl, libtime-modules-perl, 
 libyaml-perl, libtree-simple-perl, ${misc:Depends}, ${perl:Depends}, 
 debconf | debconf-2.0, ucf (>= 0.28)
Description: RT FAQ Manager
 RTFM is a knowledge management tool implemented as an add-on to RT that
 enables an organization to easily capture and share its employees'
 knowledge and wisdom.
 .
 Just as you use RT (Request Tracker, the open-source ticketing system) to log
 tickets and resolve issues, RTFM lets you open, categorize and search for
 'articles'. Like RT, RTFM lets users contribute additional information
 to existing articles. It guarantees that each article's full history is
 preserved for future inspection. RTFM simplifies browsing in the
 knowledge base and finding critical information.

More information about the pkg-request-tracker-maintainers mailing list