help strings added for all remaining config entries (so I hope)

please everybody watch out for spelling (and other) errors

CVS patchset: 6442
CVS date: 2004/04/26 17:50:06

7 files changed, 103 insertions, 43 deletions

diff --git a/src/xine-engine/audio_decoder.c b/src/xine-engine/audio_decoder.c
index 05642fc84..1b4c68457 100644
--- a/src/xine-engine/audio_decoder.c
+++ b/src/xine-engine/audio_decoder.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: audio_decoder.c,v 1.127 2004/03/28 19:51:56 mroi Exp $
+ * $Id: audio_decoder.c,v 1.128 2004/04/26 17:50:12 mroi Exp $
  *
  *
  * functions that implement audio decoding
@@ -449,9 +449,12 @@ void _x_audio_decoder_init (xine_stream_t *stream) {
     num_buffers = stream->xine->config->register_num (stream->xine->config,
                                                       "audio.num_buffers",
                                                       230,
-                                                      "number of audio buffers to allocate (higher values mean smoother playback but higher latency)",
-                                                      NULL, 20,
-                                                      NULL, NULL);
+                                                      _("number of audio buffers"),
+						      _("The number of audio buffers (each is 8k in size) "
+						        "xine uses in its internal queue. Higher values "
+							"mean smoother playback for unreliable inputs, but "
+							"also increased latency and memory comsumption."),
+                                                      20, NULL, NULL);
   
     stream->audio_fifo = _x_fifo_buffer_new (num_buffers, 8192);
     stream->audio_channel_user = -1;
diff --git a/src/xine-engine/audio_out.c b/src/xine-engine/audio_out.c
index 9247e3411..e263b73e5 100644
--- a/src/xine-engine/audio_out.c
+++ b/src/xine-engine/audio_out.c
@@ -17,7 +17,7 @@
  * along with self program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
  *
- * $Id: audio_out.c,v 1.171 2004/04/07 18:07:25 mroi Exp $
+ * $Id: audio_out.c,v 1.172 2004/04/26 17:50:12 mroi Exp $
  *
  * 22-8-2001 James imported some useful AC3 sections from the previous alsa driver.
  *   (c) 2001 Andy Lo A Foe <andy@alsaplayer.org>
@@ -1843,7 +1843,7 @@ xine_audio_port_t *_x_ao_new_port (xine_t *xine, ao_driver_t *driver,
   int              i, err;
   pthread_attr_t   pth_attrs;
   static     char *resample_modes[] = {"auto", "off", "on", NULL};
-  static     char *av_sync_methods[] = {"metronom_feedback", "resample", NULL};
+  static     char *av_sync_methods[] = {"metronom feedback", "resample", NULL};
 
   this = xine_xmalloc (sizeof (aos_t)) ;
 
@@ -1883,26 +1883,59 @@ xine_audio_port_t *_x_ao_new_port (xine_t *xine, ao_driver_t *driver,
 
   this->av_sync_method_conf = config->register_enum(config, "audio.av_sync_method", 0,
                                                     av_sync_methods,
-                                                    _("choose method to sync audio and video"),
-                                                    _("'resample' might be better if you use a "
-                                                      "DXR3/H+ card and (analog) audio is "
-                                                      "processed by your sound card"),
-                                                    30, ao_update_av_sync_method, this);
+                                                    _("method to sync audio and video"),
+						    _("When playing audio and video, there are at least "
+						      "two clocks involved: The system clock, to which "
+						      "video frames are synchronized and the clock "
+						      "in your sound hardware, which determines the "
+						      "speed of the audio playback. These clocks are "
+						      "never ticking at the same speed except for some "
+						      "rare cases where they are physically identical. "
+						      "In general, the two clocks will run drift after "
+						      "some time, for which xine offers two ways to "
+						      "keep audio and video synchronized:\n\n"
+						      "metronom feedback\n"
+						      "This is the standard method, which applies a "
+						      "countereffecting video drift, as soon as the audio "
+						      "drift has accumulated over a threshold.\n\n"
+						      "resample\n"
+						      "For some video hardware, which is limited to a "
+						      "fixed frame rate (like the DXR3 or other decoder "
+						      "cards) the above does not work, because the video "
+						      "cannot drift. Therefore we resample the audio "
+						      "stream to make it longer or shorter to compensate "
+						      "the audio drift error. This does not work for "
+						      "digital passthrough, where audio data is passed to "
+						      "an external decoder in digital form."),
+                                                    20, ao_update_av_sync_method, this);
   config->update_num(config,"audio.av_sync_method",this->av_sync_method_conf);
   
   this->resample_conf = config->register_enum (config, "audio.resample_mode", 0,
 					       resample_modes,
-					       _("adjust whether resampling is done or not"),
-					       NULL, 20, NULL, NULL);
+					       _("enable resampling"),
+					       _("When the sample rate of the decoded audio does not "
+						 "match the capabilities of your sound hardware, an "
+						 "adaptation called \"resampling\" is required. Here you "
+						 "can select, whether resampling is enabled, disabled or "
+						 "used automatically when necessary."),
+					       20, NULL, NULL);
   this->force_rate    = config->register_num (config, "audio.force_rate", 0,
-					      _("if !=0 always resample to given rate"),
-					      NULL, 20, NULL, NULL);
+					      _("always resample to this rate (0 to disable)"),
+					      _("Some audio drivers do not correctly announce the "
+						"capabilities of the audio hardware. By setting a "
+						"value other than zero here, you can force the audio "
+						"stream to be resampled to the given rate."),
+					      20, NULL, NULL);
 
   this->passthrough_offset = config->register_num (config,
 						   "audio.passthrough_offset",
 						   0,
-						   _("adjust if audio is offsync"),
-						   NULL, 10, NULL, NULL);
+						   _("offset for digital passthrough"),
+						   _("If you use an external surround decoder and "
+						     "audio is ahead or behind video, you can enter "
+						     "a fixed offset here to compensate.\nThe unit of "
+						     "the value is one PTS tick, which is the 90000th "
+						     "part of a second."), 10, NULL, NULL);
 
   this->compression_factor     = 2.0;
   this->compression_factor_max = 0.0;
@@ -1968,13 +2001,13 @@ xine_audio_port_t *_x_ao_new_port (xine_t *xine, ao_driver_t *driver,
     int vol;
     
     vol = config->register_range (config, "audio.mixer_volume", 
-				  50, 0, 100, _("Audio volume"), 
-				  NULL, 0, NULL, NULL);
+				  50, 0, 100, _("startup audio volume"), 
+				  _("The overall audio volume set at xine startup."), 10, NULL, NULL);
     
     if(config->register_bool (config, "audio.remember_volume", 0,
 			      _("restore volume level at startup"), 
-			      _("if this not set, xine will not touch any mixer settings at startup"),
-			      0, NULL, NULL)) {
+			      _("If disabled, xine will not modify any mixer settings at startup."),
+			      10, NULL, NULL)) {
       int prop = 0;
 
       if((ao_get_capabilities(&this->ao)) & AO_CAP_MIXER_VOL)
diff --git a/src/xine-engine/load_plugins.c b/src/xine-engine/load_plugins.c
index 92bbaef66..03cc5bb64 100644
--- a/src/xine-engine/load_plugins.c
+++ b/src/xine-engine/load_plugins.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: load_plugins.c,v 1.174 2004/04/11 14:51:20 mroi Exp $
+ * $Id: load_plugins.c,v 1.175 2004/04/26 17:50:12 mroi Exp $
  *
  *
  * Load input/demux/audio_out/video_out/codec plugins
@@ -303,6 +303,7 @@ static void _insert_plugin (xine_t *this,
   uint32_t          *types;
   int                priority = 0;
   char               key[80];
+  char               desc[100];
   int                i;
 
   if (info->API != api_version) {
@@ -359,13 +360,14 @@ static void _insert_plugin (xine_t *this,
     priority = decoder_new->priority = decoder_old->priority;
     
     sprintf(key, "decoder.%s_priority", info->id);
+    sprintf(desc, _("priority for decoder %s"), info->id);
     this->config->register_num (this->config,
 				key,
 				0,
-				"decoder's priority compared to others",
-				"The priority provides a ranking in case some media "
-				"can be handled by more than one decoder.\n"
-				"A priority of 0 enables the decoder's default priority.", 20,
+				desc,
+				_("The priority provides a ranking in case some media "
+				  "can be handled by more than one decoder.\n"
+				  "A priority of 0 enables the decoder's default priority."), 20,
 				_decoder_priority_cb, (void *)this);
 
     /* reset priority on old config files */
diff --git a/src/xine-engine/osd.c b/src/xine-engine/osd.c
index eeb40b02a..876fbc9cf 100644
--- a/src/xine-engine/osd.c
+++ b/src/xine-engine/osd.c
@@ -1375,8 +1375,11 @@ osd_renderer_t *_x_osd_renderer_init( xine_stream_t *stream ) {
   this->textpalette = this->stream->xine->config->register_enum (this->stream->xine->config,
                                              "misc.osd_text_palette", 0,
                                              textpalettes_str, 
-                                             _("Palette (foreground-border-background) to use on subtitles"),
-                                             NULL, 10, update_text_palette, this);
+                                             _("palette (foreground-border-background) to use for subtitles and OSD"),
+                                             _("The palette for on-screen-display and some subtitle formats that do "
+					       "not specify any colouring themselves. The palettes are listed in the "
+					       "form: foreground-border-background."),
+                                             10, update_text_palette, this);
   
   /*
    * set up function pointer
diff --git a/src/xine-engine/video_decoder.c b/src/xine-engine/video_decoder.c
index 0255d71fe..c0c4af95c 100644
--- a/src/xine-engine/video_decoder.c
+++ b/src/xine-engine/video_decoder.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: video_decoder.c,v 1.148 2004/04/08 13:37:54 mroi Exp $
+ * $Id: video_decoder.c,v 1.149 2004/04/26 17:50:12 mroi Exp $
  *
  */
 
@@ -456,9 +456,12 @@ void _x_video_decoder_init (xine_stream_t *stream) {
     num_buffers = stream->xine->config->register_num (stream->xine->config,
                                                       "video.num_buffers",
                                                       500,
-                                                      "number of video buffers to allocate (higher values mean smoother playback but higher latency)",
-                                                      NULL, 20,
-                                                      NULL, NULL);
+                                                      _("number of video buffers"),
+						      _("The number of video buffers (each is 8k in size) "
+						        "xine uses in its internal queue. Higher values "
+							"mean smoother playback for unreliable inputs, but "
+							"also increased latency and memory comsumption."),
+                                                      20, NULL, NULL);
   
     stream->video_fifo = _x_fifo_buffer_new (num_buffers, 8192);
     stream->spu_track_map_entries = 0;
diff --git a/src/xine-engine/video_out.c b/src/xine-engine/video_out.c
index 65a7f7d56..2f8deadf0 100644
--- a/src/xine-engine/video_out.c
+++ b/src/xine-engine/video_out.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: video_out.c,v 1.190 2004/04/22 23:19:04 tmattern Exp $
+ * $Id: video_out.c,v 1.191 2004/04/26 17:50:13 mroi Exp $
  *
  * frame allocation / queuing / scheduling / output functions
  */
@@ -1550,12 +1550,16 @@ xine_video_port_t *_x_vo_new_port (xine_t *xine, vo_driver_t *driver,
 
   this->warn_skipped_threshold = 
     xine->config->register_num (xine->config, "video.warn_skipped_threshold", 10,
-    "send event to front end if percentage of skipped frames exceed this value",
-    NULL, 20, NULL, NULL);
+    _("percentage of skipped frames to tolerate"),
+    _("When more than this percentage of frames are not shown, because they "
+      "were not decoded in time, xine sends a notification."),
+    20, NULL, NULL);
   this->warn_discarded_threshold = 
     xine->config->register_num (xine->config, "video.warn_discarded_threshold", 10,
-    "send event to front end if percentage of discarded frames exceed this value",
-    NULL, 20, NULL, NULL);
+    _("percentage of discarded frames to tolerate"),
+    _("When more than this percentage of frames are not shown, because they "
+      "were not scheduled for display in time, xine sends a notification."),
+    20, NULL, NULL);
 
 
   if (grabonly) {
diff --git a/src/xine-engine/xine.c b/src/xine-engine/xine.c
index 625915008..d34db5c31 100644
--- a/src/xine-engine/xine.c
+++ b/src/xine-engine/xine.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: xine.c,v 1.290 2004/04/16 16:34:22 hadess Exp $
+ * $Id: xine.c,v 1.291 2004/04/26 17:50:13 mroi Exp $
  */
 
 /*
@@ -1459,9 +1459,18 @@ void xine_init (xine_t *this) {
   this->demux_strategy  = this->config->register_enum (
       this->config, "misc.demux_strategy", 0,
       demux_strategies,
-      _("Media format detection strategy"),
-      NULL, 
-      10, __config_demux_strategy_cb, this);
+      _("media format detection strategy"),
+      _("xine offers various methods to detect the media format of input to play. "
+	"The individual values are:\n\n"
+	"default\n"
+	"First try to detect by content, then by file name extension.\n\n"
+	"reverse\n"
+	"First try to detect by file name extension, then by content.\n\n"
+	"content\n"
+	"Detect by content only.\n\n"
+	"extension\n"
+	"Detect by file name extension only.\n"),
+      20, __config_demux_strategy_cb, this);
 
   /*
    * save directory
@@ -1469,8 +1478,11 @@ void xine_init (xine_t *this) {
   this->save_path  = this->config->register_string (
       this->config, 
       "misc.save_dir", "",
-      _("Path for saving streams"),
-      _("Streams will be saved only into this directory"),
+      _("directory for saving streams"),
+      _("When using the stream save feature, files will be written only into this directory.\n"
+	"This setting is security critical, because when changed to a different directory, xine "
+	"can be used to fill files in it with arbitrary content. So you should be careful that "
+	"the directory you specify is robust against any content in any file."),
       XINE_CONFIG_SECURITY, __config_save_cb, this);
   
   /*