improving config help strings

CVS patchset: 6383
CVS date: 2004/04/10 15:45:10

9 files changed, 145 insertions, 81 deletions

diff --git a/src/input/input_cdda.c b/src/input/input_cdda.c
index 159847e8c..5e4f33d4f 100644
--- a/src/input/input_cdda.c
+++ b/src/input/input_cdda.c
@@ -20,7 +20,7 @@
  * Compact Disc Digital Audio (CDDA) Input Plugin 
  *   by Mike Melanson (melanson@pcisys.net)
  *
- * $Id: input_cdda.c,v 1.48 2004/04/10 14:27:37 miguelfreitas Exp $
+ * $Id: input_cdda.c,v 1.49 2004/04/10 15:45:10 mroi Exp $
  */
 
 #ifdef HAVE_CONFIG_H
@@ -2409,24 +2409,39 @@ static void *init_plugin (xine_t *xine, void *data) {
   
   this->cdda_device = config->register_string(config, "input.cdda_device", 
 					      DEFAULT_CDDA_DEVICE,
-					      _("device used for cdda drive"), NULL, 20, 
-					      cdda_device_cb, (void *) this);
+					      _("device used for CD audio"),
+					      _("The path to the device, usually a "
+						"CD or DVD drive, which you intend to use "
+						"for playing audio CDs."),
+					      10, cdda_device_cb, (void *) this);
   
   config->register_bool(config, "input.cdda_use_cddb", 1,
-			_("use cddb feature"), NULL, 10,
-			enable_cddb_changed_cb, (void *) this);
+			_("query CDDB"), _("Enables CDDB queries, which will give you "
+			"convenient title and track names for your audio CDs.\n"
+			"Keep in mind that, unless you use your own private CDDB, this information "
+			"is retrieved from an internet server which might collect a profile "
+			"of your listening habits."),
+			10, enable_cddb_changed_cb, (void *) this);
   
   config->register_string(config, "input.cdda_cddb_server", CDDB_SERVER,
-			  _("cddbp server name"), NULL, 10,
+			  _("CDDB server name"), _("The CDDB server used to retrieve the "
+			  "title and track information from.\nThis setting is security critical, "
+			  "because the sever will receive information about your listening habits "
+			  "and could answer the queries with malicious replies. Be sure to enter "
+			  "a server you can trust."), XINE_CONFIG_SECURITY,
 			  server_changed_cb, (void *) this);
   
   config->register_num(config, "input.cdda_cddb_port", CDDB_PORT,
-		       _("cddbp server port"), NULL, 10,
+		       _("CDDB server port"), _("The server port used to retrieve the "
+		       "title and track information from."), XINE_CONFIG_SECURITY,
 		       port_changed_cb, (void *) this);
   
   config->register_string(config, "input.cdda_cddb_cachedir", 
 			  (_cdda_cddb_get_default_location()),
-			  _("cddbp cache directory"), NULL, 20, 
+			  _("CDDB cache directory"), _("The replies from the CDDB server will be "
+			  "cached in this directory.\nThis setting is security critical, because files "
+			  "with uncontrollable names will be created in this directory. Be sure to use "
+			  "a dedicated directory not used for anything but CDDB caching."), XINE_CONFIG_SECURITY, 
 			  cachedir_changed_cb, (void *) this);
 
   this->cddb_error = 0;
diff --git a/src/input/input_dvd.c b/src/input/input_dvd.c
index 11031882c..899487819 100644
--- a/src/input/input_dvd.c
+++ b/src/input/input_dvd.c
@@ -18,7 +18,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
  *
- * $Id: input_dvd.c,v 1.179 2003/12/26 16:13:21 mroi Exp $
+ * $Id: input_dvd.c,v 1.180 2004/04/10 15:45:10 mroi Exp $
  *
  */
 
@@ -1654,9 +1654,10 @@ static void *init_class (xine_t *xine, void *data) {
   this->dvd_device = config->register_string(config,
 					     "input.dvd_device",
 					     DVD_PATH,
-					     "device used for dvd drive",
-					     NULL,
-					     0, device_change_cb, (void *)this);
+					     _("device used for DVD playback"),
+					     _("The path to the device, usually a "
+					       "DVD drive, which you intend to use for playing DVDs."),
+					     10, device_change_cb, (void *)this);
   
   if ((dvdcss = dlopen("libdvdcss.so.2", RTLD_LAZY)) != NULL) {
     /* we have found libdvdcss, enable the specific config options */
@@ -1666,20 +1667,37 @@ static void *init_class (xine_t *xine, void *data) {
     int mode;
     
     raw_device = config->register_string(config, "input.dvd_raw_device",
-					 RDVD_PATH, "raw device set up for dvd access",
-					 NULL, 10, NULL, NULL);
+					 RDVD_PATH, _("raw device set up for DVD access"),
+					 _("If this points to a raw device connected to your "
+					   "DVD device, xine will use the raw device for playback. "
+					   "This has the advantage of being slightly faster and "
+					   "of bypassing the block device cache, which avoids "
+					   "throwing away important cache content by keeping DVD "
+					   "data cached. Using the block device cache for DVDs "
+					   "is useless, because almost all DVD data will be used "
+					   "only once.\nSee the documentation on raw device setup "
+					   "(man raw) for further information."),
+					 10, NULL, NULL);
     if (raw_device) xine_setenv("DVDCSS_RAW_DEVICE", raw_device, 0);
     
     mode = config->register_enum(config, "input.css_decryption_method", 0,
-				 decrypt_modes, "the css decryption method libdvdcss should use",
-				 NULL, 10, NULL, NULL);
+				 decrypt_modes, _("CSS decryption method"),
+				 _("Selects the decryption method libdvdcss will use to descramble "
+				   "copy protected DVDs. Try the various methods, if you have problems "
+				   "playing scrambled DVDs."), 20, NULL, NULL);
     xine_setenv("DVDCSS_METHOD", decrypt_modes[mode], 0);
     
     css_cache_default = (char *)malloc(strlen(xine_get_homedir()) + 10);
     sprintf(css_cache_default, "%s/.dvdcss/", xine_get_homedir());
     css_cache = config->register_string(config, "input.css_cache_path", css_cache_default,
-					"path to the libdvdcss title key cache",
-					NULL, 10, NULL, NULL);
+					_("path to the title key cache"),
+					_("Since cracking the copy protection of scrambled DVDs can "
+					  "be quite time consuming, libdvdcss will cache the cracked "
+					  "keys in this directory.\nThis setting is security critical, "
+					  "because files with uncontrollable names will be created in "
+					  "this directory. Be sure to use a dedicated directory not "
+					  "used for anything but DVD key caching."),
+					XINE_CONFIG_SECURITY, NULL, NULL);
     if (strlen(css_cache) > 0)
       xine_setenv("DVDCSS_CACHE", css_cache, 0);
     free(css_cache_default);
@@ -1695,34 +1713,53 @@ static void *init_class (xine_t *xine, void *data) {
   
   config->register_num(config, "input.dvd_region",
 		       1,
-		       "Region that DVD player claims "
-		       "to be (1 -> 8)",
-		       "This only needs to be changed "
-		       "if your DVD jumps to a screen "
-		       "complaining about region code ",
+		       _("region the DVD player claims to be in (1 to 8)"),
+		       _("This only needs to be changed if your DVD jumps to a screen "
+		         "complaining about a wrong region code. It has nothing to do with "
+		         "the region code set in DVD drives, this is purely software."),
 		       0, region_changed_cb, this);
   config->register_string(config, "input.dvd_language",
 			  "en",
-			  "The default language for dvd",
-			  "The dvdnav plugin tries to use this "
-			  "language as a default. This must be a"
-			  "two character ISO country code.",
+			  _("default language for DVD playback"),
+			  _("xine tries to use this language as a default for DVD playback. "
+			    "As far as the DVD supports it, menus and audio tracks will be presented "
+			    "in this language.\nThe value must be a two character ISO639 language code."),
 			  0, language_changed_cb, this);
   config->register_bool(config, "input.dvd_use_readahead",
 			1,
-			"Do we use read-ahead caching?",
-			"This "
-			"may lead to jerky playback on low-end "
-			"machines.",
+			_("read-ahead caching"),
+			_("xine can use a read ahead cache for DVD drive access.\n"
+			  "This may lead to jerky playback on slow drives, but it improves the impact "
+			  "of the DVD layer change on faster drives."),
 			10, read_ahead_cb, this);
   config->register_enum(config, "input.dvd_skip_behaviour", 0,
 			skip_modes,
-			"Skipping will work on this basis.",
-			NULL, 10, NULL, NULL);
+			_("unit for the skip action"),
+			_("You can configure the behaviour when issuing a skip command (using the skip "
+			  "buttons for example). The individual values mean:\n\n"
+			  "skip program\n"
+			  "will skip a DVD program, which is a navigational unit similar to the "
+			  "index marks on an audio CD; this is the normal behaviour for DVD players\n\n"
+			  "skip part\n"
+			  "will skip a DVD part, which is a structural unit similar to the "
+			  "track marks on an audio CD; parts usually coincide with programs, but parts "
+			  "can be larger than programs\n\n"
+			  "skip title\n"
+			  "will skip a DVD title, which is a structural unit representing entire "
+			  "features on the DVD"),
+			20, NULL, NULL);
   config->register_enum(config, "input.dvd_seek_behaviour", 0,
 			seek_modes,
-			"Seeking will work on this basis.",
-			NULL, 10, seek_mode_cb, this);
+			_("unit for seeking"),
+			_("You can configure the domain spanned by the seek slider. The individual "
+			  "values mean:\n\n"
+			  "seek in program chain\n"
+			  "seeking will span an entire DVD program chain, which is a navigational "
+			  "unit representing the entire video stream of the current feature\n\n"
+			  "seek in program\n"
+			  "seeking will span a DVD program, which is a navigational unit representing "
+			  "a chapter of the current feature"),
+			20, seek_mode_cb, this);
 
 #ifdef __sun
   check_solaris_vold_device(this);
@@ -1736,6 +1773,9 @@ static void *init_class (xine_t *xine, void *data) {
 
 /*
  * $Log: input_dvd.c,v $
+ * Revision 1.180  2004/04/10 15:45:10  mroi
+ * improving config help strings
+ *
  * Revision 1.179  2003/12/26 16:13:21  mroi
  * * cure the ABI breakage: XINE_LANG_MAX cannot be increased
  * * add TODO items to provide a better solution
diff --git a/src/input/input_file.c b/src/input/input_file.c
index bf26e2b25..8a6b1bfbf 100644
--- a/src/input/input_file.c
+++ b/src/input/input_file.c
@@ -17,7 +17,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
  *
- * $Id: input_file.c,v 1.89 2003/12/14 22:13:23 siggi Exp $
+ * $Id: input_file.c,v 1.90 2004/04/10 15:45:11 mroi Exp $
  */
 
 #ifdef HAVE_CONFIG_H
@@ -845,15 +845,17 @@ static void *init_plugin (xine_t *xine, void *data) {
     this->origin_path = config->register_string(config, "input.file_origin_path",
 						current_dir, 
 						_("file browsing start location"),
-						NULL, 0, origin_change_cb, 
-						(void *) this);
+						_("The browser to select the file to play will "
+						  "start at this location."),
+						0, origin_change_cb, (void *) this);
   }
   
   this->show_hidden_files = config->register_bool(config, 
 						  "input.file_hidden_files", 
-						  1, _("list hidden files"),
-						  NULL, 10, hidden_bool_cb, 
-						  (void *) this);
+						  0, _("list hidden files"),
+						  _("If enabled, the browser to select the file to "
+						    "play will also show hidden files."),
+						  10, hidden_bool_cb, (void *) this);
   
   return this;
 }
diff --git a/src/input/input_http.c b/src/input/input_http.c
index 0fc6a0e3d..d6afd9511 100644
--- a/src/input/input_http.c
+++ b/src/input/input_http.c
@@ -19,7 +19,7 @@
  *
  * input plugin for http network streams
  *
- * $Id: input_http.c,v 1.84 2004/03/31 07:42:50 valtri Exp $
+ * $Id: input_http.c,v 1.85 2004/04/10 15:45:11 mroi Exp $
  */
 
 #ifdef HAVE_CONFIG_H
@@ -938,23 +938,23 @@ static void *init_class (xine_t *xine, void *data) {
   this->proxyhost_env = NULL;
   this->proxyhost = config->register_string(config, 
       "input.http_proxy_host", "", _("HTTP proxy host"),
-      _("HTTP proxy server used for http streaming"), 0,
+      _("The hostname of the HTTP proxy."), 10,
       proxy_host_change_cb, (void *) this);
   this->proxyport = config->register_num(config,
       "input.http_proxy_port", DEFAULT_HTTP_PORT, _("HTTP proxy port"),
-      _("HTTP proxy port used for http streaming"), 0,
+      _("The port number of the HTTP proxy."), 10,
       proxy_port_change_cb, (void *) this);
   this->proxyuser = config->register_string(config,
       "input.http_proxy_user", "", _("HTTP proxy username"),
-      _("HTTP proxy user used for http streaming"), 0,
+      _("The user name for the HTTP proxy."), 10,
       proxy_user_change_cb, (void *) this);
   this->proxypassword = config->register_string(config,
       "input.http_proxy_password", "", _("HTTP proxy password"),
-      _("HTTP proxy password used for http streaming"), 0, 
+      _("The password for the HTTP proxy."), 10,
       proxy_password_change_cb, (void *) this);
   this->noproxylist = config->register_string(config,
-      "input.http_no_proxy", "", _("Sites, where don't use HTTP proxy"),
-      _("Comma separated domains, where xine shouldn't use proxy"), 0,
+      "input.http_no_proxy", "", _("Domains, where to ignore the HTTP proxy"),
+      _("A Comma separated list of domain names, where the proxy is to be ignored."), 10,
       no_proxy_list_change_cb, (void *) this);
 
   /* 
diff --git a/src/input/input_mms.c b/src/input/input_mms.c
index 773fbc529..0473f4fd3 100644
--- a/src/input/input_mms.c
+++ b/src/input/input_mms.c
@@ -17,7 +17,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
  *
- * $Id: input_mms.c,v 1.48 2004/04/07 19:44:29 mroi Exp $
+ * $Id: input_mms.c,v 1.49 2004/04/10 15:45:11 mroi Exp $
  *
  * mms input plugin based on work from major mms
  */
@@ -456,15 +456,18 @@ static void *init_class (xine_t *xine, void *data) {
 
   xine->config->register_enum(xine->config, "input.mms_network_bandwidth", 10,
 			      (char **)mms_bandwidth_strs,
-			      _("Network bandwidth"),
-			      NULL, 0, bandwidth_changed_cb, (void*) this);
+			      _("network bandwidth"),
+			      _("Specify the bandwidth of your internet connection here. "
+			        "This will be used when streaming servers offer different versions "
+				"with different bandwidth requirements of the same stream."),
+			      0, bandwidth_changed_cb, (void*) this);
 
   this->protocol = xine->config->register_enum(xine->config,
     "input.mms_protocol", 
     0, 
     (char **)mms_protocol_strs, 
     _("MMS protocol"),
-    _("Select the protocol above MMS. TCP is better but you may need HTTP behind the firewall."),
+    _("Select the protocol to encapsulate MMS.\nTCP is better but you may need HTTP behind a firewall."),
      20, 
      protocol_changed_cb, (void*)this);
 
diff --git a/src/input/input_pvr.c b/src/input/input_pvr.c
index fd2117a96..a9497f5fc 100644
--- a/src/input/input_pvr.c
+++ b/src/input/input_pvr.c
@@ -38,7 +38,7 @@
  * usage: 
  *   xine pvr:/<prefix_to_tmp_files>\!<prefix_to_saved_files>\!<max_page_age>
  *
- * $Id: input_pvr.c,v 1.43 2004/03/03 20:09:12 mroi Exp $
+ * $Id: input_pvr.c,v 1.44 2004/04/10 15:45:11 mroi Exp $
  */
 
 /**************************************************************************
@@ -1538,7 +1538,7 @@ static void *init_plugin (xine_t *xine, void *data) {
 				    "input.pvr_device",
 				    PVR_DEVICE,
 				    _("device used for WinTV-PVR 250/350 (pvr plugin)"),
-				    NULL,
+				    _("The path to the device of your WinTV card."),
 				    10, NULL,
 				    NULL);
 
diff --git a/src/input/input_v4l.c b/src/input/input_v4l.c
index 2789777f2..17ff3c06f 100644
--- a/src/input/input_v4l.c
+++ b/src/input/input_v4l.c
@@ -1918,8 +1918,9 @@ static void *init_video_class (xine_t *xine, void *data)
   
   config->register_string (config, "input.v4l_video_device_path",
 			   VIDEO_DEV,
-			   _("path to the v4l video device"),
-			   NULL, 10, NULL, NULL);
+			   _("v4l video device"),
+			   _("The path to your Video4Linux video device."),
+			   10, NULL, NULL);
   
   return this;
 }
@@ -1943,8 +1944,9 @@ static void *init_radio_class (xine_t *xine, void *data)
   
   config->register_string (config, "input.v4l_radio_device_path",
 			   RADIO_DEV,
-			   _("path to the v4l radio device"),
-			   NULL, 10, NULL, NULL);
+			   _("v4l radio device"),
+			   _("The path to your Video4Linux radio device."),
+			   10, NULL, NULL);
   
   return this;
 }
diff --git a/src/input/input_vcd.c b/src/input/input_vcd.c
index a78bdde00..d19378a2d 100644
--- a/src/input/input_vcd.c
+++ b/src/input/input_vcd.c
@@ -17,7 +17,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
  *
- * $Id: input_vcd.c,v 1.72 2004/01/07 22:21:40 hadess Exp $
+ * $Id: input_vcd.c,v 1.73 2004/04/10 15:45:11 mroi Exp $
  *
  */
 
@@ -1091,8 +1091,10 @@ static void *init_class (xine_t *xine, void *data) {
   this->input_class.eject_media        = vcd_class_eject_media;
 
   this->device = config->register_string (config, "input.vcd_device", CDROM,
-					  _("path to your local vcd device file"),
-					  NULL, 10, device_change_cb, (void *)this);
+					  _("device used for VCD playback"),
+					  _("The path to the device, usually a CD or DVD drive, "
+					    "you intend to play your VideoCDs with."),
+					  10, device_change_cb, (void *)this);
 
   this->mrls = (xine_mrl_t **) xine_xmalloc(sizeof(xine_mrl_t*));
   this->mrls_allocated_entries = 0;
diff --git a/src/input/vcd/xineplug_inp_vcd.c b/src/input/vcd/xineplug_inp_vcd.c
index 15780c29e..ba9b9050e 100644
--- a/src/input/vcd/xineplug_inp_vcd.c
+++ b/src/input/vcd/xineplug_inp_vcd.c
@@ -1,5 +1,5 @@
 /*
-  $Id: xineplug_inp_vcd.c,v 1.15 2004/04/05 18:01:09 hadess Exp $
+  $Id: xineplug_inp_vcd.c,v 1.16 2004/04/10 15:45:11 mroi Exp $
  
   Copyright (C) 2002, 2003, 2004 Rocky Bernstein <rocky@panix.com>
   
@@ -1658,9 +1658,9 @@ vcd_init (xine_t *xine, void *data)
                             VCDPLAYER_AUTOPLAY_PBC,
                             (char **) autoplay_modes,
                             _("default type to use on VCD autoplay"),
-_("What play unit to use when none is specified in an MRL, e.g. "
+_("The play unit to use when none is specified in an MRL, e.g. "
                             "vcd:// or vcd:///dev/dvd:"),
-                            0, 
+                            10, 
                             vcd_default_autoplay_cb, class);
     
     
@@ -1669,7 +1669,7 @@ _("What play unit to use when none is specified in an MRL, e.g. "
                               "vcd.default_device",
                               "",
           _("default CD drive used for VCD when none given"),
-_("What to use if no drive specified. If null, we'll scan for CD drives."), 
+_("What to use if no drive specified. If the setting is empty, xine will scan for CD drives."), 
                               20,
                               vcd_default_dev_changed_cb, 
                               (void *) class));
@@ -1681,7 +1681,7 @@ _("What to use if no drive specified. If null, we'll scan for CD drives."),
                             (char **) length_reporting_modes,
                             _("position slider range"),
 _("The range the stream playback position slider represents when playing."),
-                            0, 
+                            10, 
                             vcd_slider_length_cb, NULL);
 
 #if READAHEAD_FINISHED
@@ -1699,9 +1699,9 @@ _("The range the stream playback position slider represents when playing."),
     config->register_bool(config, 
                         "vcd.autoadvance",
                         (int) true,
-                        _("Automatically advance track/entry?"),
-_("If set, we should we automatically advance to the next entry or track. Used only when playback control (PBC) is not on."),
-                        0, 
+                        _("automatically advance track/entry"),
+_("If enabled, we should automatically advance to the next entry or track. Used only when playback control (PBC) is disabled."),
+                        10, 
                         vcd_autoadvance_cb, 
                         NULL); 
 
@@ -1709,11 +1709,11 @@ _("If set, we should we automatically advance to the next entry or track. Used o
     config->register_bool(config, 
                         "vcd.show_rejected",
                         (int) false,
-                        _("Show 'rejected' LIDs?"),
-"Some playback list IDs (LIDs) are marked not showable, "
-"but you can see then in the MRL list if this is set. Rejected entries "
-"are marked with an asterisk (*) appended in the MRL.",
-                        0, 
+                        _("show 'rejected' LIDs"),
+_("Some playback list IDs (LIDs) are marked not showable, "
+"but you can see them in the MRL list if this is set. Rejected entries "
+"are marked with an asterisk (*) appended to the MRL."),
+                        10, 
                         vcd_show_rejected_cb, 
                         NULL); 
 
@@ -1723,9 +1723,9 @@ _("If set, we should we automatically advance to the next entry or track. Used o
                           "%F - %I %N%L%S, disk %c of %C - %v %A",
                           _("format string for display banner"),
 _("Format used in the GUI Title. Similar to the Unix date "
-"command. Format specifiers that start with a percent sign. Specifiers are "
+"command. Format specifiers start with a percent sign. Specifiers are "
 "%A, %C, %c, %F, %I, %L, %N, %P, %p, %S, %T, %V, %v, and %%."),
-                          0,
+                          20,
                           vcd_title_format_changed_cb,
                           NULL));
 
@@ -1735,9 +1735,9 @@ _("Format used in the GUI Title. Similar to the Unix date "
                           "%P - Track %T",
                           _("format string for stream comment field"),
 _("Format used in the GUI Title. Similar to the Unix date "
-"command. Format specifiers that start with a percent sign. Specifiers are "
-"same as the title_format."),
-                          0,
+"command. Format specifiers start with a percent sign. Specifiers are "
+"%A, %C, %c, %F, %I, %L, %N, %P, %p, %S, %T, %V, %v, and %%."),
+                          20,
                           vcd_comment_format_changed_cb,
                           NULL));
 
@@ -1746,8 +1746,8 @@ _("Format used in the GUI Title. Similar to the Unix date "
                        "vcd.debug",
                        0,
                        _("debug flag mask"),
-                       _("This integer when viewed in binary is a debugging mask"),
-                        0, 
+                       _("This integer is a debugging mask when interpreted in binary."),
+                        20,
                         vcd_debug_cb, 
                         class); 
   }