Make factual and grammatical corrections to man pages. Add simple description of...

Original commit message from CVS:
Make factual and grammatical corrections to man pages.  Add simple
description of pipelines.

diff --git a/tools/gst-complete.1 b/tools/gst-complete.1
index 9ff8315..c4af6be 100644 (file)
--- a/tools/gst-complete.1
+++ b/tools/gst-complete.1
@@ -8,9 +8,10 @@ gst\-complete - do bash completion for gst\-launch command\-lines
 \fIgst\-complete\fP is a utility enabling bash to provide
 context sensitive tab completion for \fIgst\-launch\fP command\-lines.
 .
-See other docs for the syntax of \fIgst\-launch\fP command\-lines.
+See the man page for \fIgst\-launch\fP for the syntax of \fIgst\-launch\fP
+command\-lines.
 .
-You must have a version of bash which supports Programmable Completion.
+You must have a version of bash which supports programmable completion.
 Versions of bash which support this provide the \fIcomplete\fP builtin
 command.
 .

diff --git a/tools/gst-compprep.1 b/tools/gst-compprep.1
index 67f743a..bf6dc0d 100644 (file)
--- a/tools/gst-compprep.1
+++ b/tools/gst-compprep.1
@@ -5,15 +5,14 @@ gst\-compprep \- create the registry for gst\-complete
 gst\-compprep
 .SH "DESCRIPTION"
 .LP 
-\fIgst\-compprep\fR is a utility to build the registry of gstreamer
-elements and their features to enable context sensitive tab completion for
-\fIgst\-launch\fR command\-lines to be performed by
-\fIgst\-complete\fR.
+\fIgst\-compprep\fR builds a registry of GStreamer elements and their
+features that is used by \fIgst\-complete\fR to perform context-sensitive
+tab completion of \fIgst\-launch\fR command lines.
 .LP 
 By default, the registry is stored in /etc/gstreamer/compreg.xml
 .SH "USAGE"
-Whenever the available gstreamer plugins are modified, generate the registry of available plugins by running
-\fIgst\-compprep\fP.
+Whenever the available gstreamer plugins are modified, the registry should
+be regenerated by running \fIgst\-compprep\fP as root.
 .SH "FILES"
 .TP 8
 /etc/gstreamer/compreg.xml

diff --git a/tools/gst-feedback.1 b/tools/gst-feedback.1
index f6a96a6..30c5f7f 100644 (file)
--- a/tools/gst-feedback.1
+++ b/tools/gst-feedback.1
@@ -5,8 +5,8 @@ gst\-feedback - generate debug info for GStreamer bug reports
 .B  gst-feedback
 .SH DESCRIPTION
 .PP
-\fIgst\-feedback\fP is a utility to scan the system for various
-information that is useful for GStreamer developers to help diagnose
+\fIgst\-feedback\fP is a utility that scans the system for various
+information that is useful to GStreamer developers to help diagnose
 user problem.
 .PP
 Depending on the type of bug report, it may be useful to attach the
@@ -23,7 +23,12 @@ Generate the feedback information by running \fIgst\-feedback\fP:
 .TP -8
 Possibly redirect output and errors to a file:
 .TP 8
-.B  gst\-feedback > myfeedback 2>&1
+.B  gst\-feedback &> myfeedback
+.SH WARNING
+The \fIgst\-feedback\fP dumps a lot of information about a system, some
+of which may be considered sensitive.  If this is a concern, review the
+information before posting to a public forum, such as the GStreamer bug
+tracking system.
 .SH SEE ALSO
 .BR gst\-launch (1),
 .BR gst\-register (1),

diff --git a/tools/gst-inspect.1 b/tools/gst-inspect.1
index 40601e4..909837e 100644 (file)
--- a/tools/gst-inspect.1
+++ b/tools/gst-inspect.1
@@ -5,14 +5,17 @@ gst\-inspect - print info about a GStreamer plugin or element
 .B  gst\-register [OPTION...] [PLUGIN|ELEMENT]
 .SH DESCRIPTION
 .PP
-\fIgst\-inspect\fP is a tool to print out information on the
-available \fIGStreamer\fP plugins, information on a plugin, or
-information on an element.  With no PLUGIN or ELEMENT option it
-will list all plugins and elements.
+\fIgst\-inspect\fP is a tool that prints out information on
+available \fIGStreamer\fP plugins, information about a particular
+plugin, or information about a particular element.  When executed
+with no PLUGIN or ELEMENT argument, \fIgst\-inspect\fP will print
+a list of all plugins and elements.  When executed with a PLUGIN
+or ELEMENT argument, \fIgst\-inspect\fP will print information
+about that plug-in or element.
 .
 .SH OPTIONS
 .l
-\fIgst\-inspect\fP accepts the following options:
+\fIgst\-inspect\fP accepts the following arguments and options:
 .TP 8
 .B  PLUGIN
 Name of a plugin

diff --git a/tools/gst-launch.1 b/tools/gst-launch.1
index cf90c70..4935f7e 100644 (file)
--- a/tools/gst-launch.1
+++ b/tools/gst-launch.1
@@ -5,92 +5,141 @@ gst\-launch \- build and run a GStreamer pipeline
 \fBgst\-launch\fR \fI[OPTION...]\fR PIPELINE\-DESCRIPTION
 .SH "DESCRIPTION"
 .LP 
-\fIgst\-launch\fP is a tool that is used to build and run a basic \fIGStreamer\fP pipeline.
+\fIgst\-launch\fP is a tool that builds and runs basic
+\fIGStreamer\fP pipelines.
 
-A simple commandline looks like:
+In simple form, a PIPELINE\-DESCRIPTION is a list of
+elements separated by exclamation marks (!).  Options may be appended to
+elements, in the form "option=value".  A group of elements
+surrounded by curly braces {, } will be executed in a separate thread.
 
- gst\-launch filesrc location=music.mp3 ! mad ! osssink
+Connections between non-consecutive elements are created by specifying
+a element names and pad names immediately before and after the
+exclamation mark, in the form "element0.sinkpad!element1.srcpad".
+The default name given to an element is the name of its class followed by
+an index.  If the element names are omitted, the previous and next
+elements in the PIPELINE-DESCRIPTION will be used.  If the pad names
+are omitted, a default pad of the correct type (source or sink) is
+found on the given element, typically named "src" or "sink".
 
-This plays an mp3 music file music.mp3 using libmad, and:
+See the GStreamer documentation for a complete description of a
+a PIPELINE\-DESCRIPTION.
 
- gst\-launch filesrc location=music.mp3 ! mp3parse ! mpg123 ! osssink
+.SH "EXAMPLES"
 
-Plays and mp3 music file using mpg123
+The examples below assume that you have the correct plug-ins available.
+In general, "osssink" can be substituted with another audio output
+plug-in such as "esdsink", "alsasink", or "artsdsink".  Likewise,
+"xvideosink" can be substituted with "sdlvideosink" or "aasink".
 
-You can also stream files over http:
+.B Audio playback
 
- gst\-launch httpsrc location=http://domain.com/music.mp3 ! mad ! osssink
+Play the mp3 music file "music.mp3" using a libmad-based plug-in and
+output to an OSS device:
 
-And using gnome\-vfs you can do the same with:
+       gst\-launch filesrc location=music.mp3 ! mad ! osssink
 
- gst\-launch gnomevfssrc location=music.mp3 ! mad ! osssink
- gst\-launch gnomevfssrc location=http://domain.com/music.mp3 ! mad ! osssink
+Play an Ogg Vorbis format file:
 
-And too play the same song with gnome\-vfs via smb:
+       gst\-launch filesrc location=music.ogg ! vorbisfile ! osssink
 
- gst\-launch gnomevfssrc location=smb://computer/music.mp3 ! mad ! osssink
+Play an mp3 file or stream retrieved via http:
 
-You can also stream your mpeg 1 system streams from one machine to another using RTP by:
- 
- gst\-launch rtprecv media_type=mpeg1_sys ! mpegdemux video_%02d! { queue ! mpeg2dec ! xvideosink } mpegdemux0.audio_%02d! { queue ! mad ! osssink }
+       gst\-launch httpsrc location=http://domain.com/music.mp3 ! mad ! osssink
+
+Play an mp3 file or stream using GNOME\-VFS:
+
+       gst\-launch gnomevfssrc location=music.mp3 ! mad ! osssink
+
+       gst\-launch gnomevfssrc location=http://domain.com/music.mp3 ! mad ! osssink
+
+Use GNOME\-VFS to play an mp3 file located on an SMB server:
+
+       gst\-launch gnomevfssrc location=smb://computer/music.mp3 ! mad ! osssink
+
+.B Format conversion
+
+Convert an mp3 music file to an Ogg Vorbis file:
+
+       gst\-launch filesrc location=music.mp3 ! mad ! vorbisenc ! filesink location=music.ogg
+
+Alternatively, to convert to the FLAC format, use the command line:
+
+       gst\-launch filesrc location=claptrap.mp3 ! mad ! flacenc ! filesink location=test.flac
 
-on the receiver end and:
+.B Other
 
- gst\-launch filesrc location=mpeg1system.mpeg ! mpegparse ! rtpsend ip=IPorHostname
+Plays a .WAV file:
 
-on the transmitter end.
+       gst\-launch filesrc location=music.wav ! wavparse ! osssink
 
-Here we convert a Mp3 file into an Ogg Vorbis file:
+Convert a .WAV file into Ogg Vorbis (or mp3) file:
 
- gst\-launch filesrc location=music.mp3 ! mad ! vorbisenc ! disksink location=music.ogg
+       gst\-launch filesrc location=music.wav ! wavparse ! vorbisenc ! filesink location=music.ogg
 
-Or converting from mp3 to Flac:
- gst\-launch filesrc location=claptrap.mp3 ! mad ! flacenc ! disksink location=test.flac
+       gst\-launch filesrc location=music.wav ! wavparse ! mpegaudio ! filesink location=music.mp3
 
-And then we can play that file with:
+Alternatively, if you have lame installed (and have the lame plug-in),
+you can substitute lame for mpegaudio in the previous example.  It gives
+better results than mpegaudio.
 
- gst\-launch filesrc location=music.ogg ! vorbisdec ! osssink
+Rip all tracks from compact disc and convert them into a single mp3 file:
 
-Some other useful pipelines are..
-Plays wav files (currently there are no wav encoders):
+       gst\-launch cdparanoia ! mpegaudio ! filesink location=cd.mp3
 
- gst\-launch filesrc location=music.wav ! parsewav ! osssink
+Using gst\-inspect, it is possible to discover settings for cdparanoia
+that will tell it to rip individual tracks.
 
-Converts wav files into mp3 and ogg files:
+Record sound from your audio input and encode it into an ogg file:
 
- gst\-launch filesrc location=music.wav ! parsewav ! vorbisenc ! disksink location=music.ogg
- gst\-launch filesrc location=music.wav ! parsewav ! mpegaudio ! disksink location=music.mp3
+       gst\-launch osssrc ! vorbisenc ! filesink location=input.ogg
 
-You can also use lame for mp3 encoding if you have it installed, it does a 
-much better job than mpegaudio.
+.B Video
 
-Rips all songs from cd and saves them into a mp3 file:
+Display only the video portion of an MPEG-1 video file, outputting to
+an X display window (The "queue" element is necessary to buffer data
+between the threads):
+
+       gst\-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! mpegdemux video_%02d!src { queue ! mpeg2dec ! xvideosink }
+
+Display the video portion of a .vob file (used on DVDs), outputting to
+an SDL window:
+
+       gst\-launch filesrc location=/flflfj.vob ! mpegdemux video_%02d!src { queue ! mpeg2dec ! sdlvideosink }
+
+Play both video and audio portions of an MPEG movie:
+
+       gst\-launch filesrc location=movie.mpg ! mpegdemux video_%02d!src { queue ! mpeg2dec ! sdlvideosink } mpegdemux0.audio_%02d!src { queue ! mad ! osssink }
+
+Play an AVI movie:
+
+       gst\-launch filesrc location=movie.avi ! avidemux video_%02d!src { queue ! windec ! sdlvideosink }
+
+.B Network streaming
+
+An MPEG\-1 system stream can be streamed via RTP from one machine to
+another.  On the receiver, execute:
+ 
+       gst\-launch rtprecv media_type=mpeg1_sys ! mpegdemux video_%02d!src { queue ! mpeg2dec ! xvideosink } mpegdemux0.audio_%02d!src { queue ! mad ! osssink }
 
- gst\-launch cdparanoia ! mpegaudio ! disksink location=cd.mp3
+On the transmitter, execute:
 
-You can toy around with gst\-inspect to discover the settings for 
-cdparanoia to rip individual tracks
+       gst\-launch filesrc location=mpeg1system.mpeg ! mpegparse ! rtpsend ip=IPorHostname
 
-Record sound from your sound input and encode it into an ogg file:
+.B Diagnostic
 
- gst\-launch osssrc ! vorbisenc ! disksink location=input.ogg
+Generate a null stream and ignore it:
 
-gst\-launch not only handles audio but video as well:
-For mpeg video files (here outputing to aasink) :
+       gst\-launch fakesrc ! fakesink
 
- gst\-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! mpegdemux video_%02d! { queue ! mpeg2dec ! aasink }
+Generate a pure tone to test the audio output:
 
-For vob files (here outputting image to sdlvideosink): 
- gst\-launch filesrc location=/flflfj.vob ! mpegdemux video_%02d! { queue ! mpeg2dec ! sdlvideosink }
+       gst\-launch sinesrc ! osssink
 
-Play a mpeg movie with sound using the sdlvideosink:
- gst\-launch filesrc location=movie.mpg ! mpegdemux video_%02d! { queue ! mpeg2dec ! sdlvideosink } mpegdemux0.audio_%02d! { queue ! mad ! osssink }
+Generate a familiar test pattern to test the video output:
 
-Playing a avi movie would be done with something like this:
-gst\-launch filesrc location=movie.avi ! avidemux video_%02d! { queue ! windec ! sdlvideosink }
+       gst\-launch videotestsrc ! xvideosink
 
-See other docs, examples, and the source for description on how to
-create a PIPELINE\-DESCRIPTION.
 .
 .SH "OPTIONS"
 .l

diff --git a/tools/gst-md5sum.1 b/tools/gst-md5sum.1
index 9bd71cb..4e6970c 100644 (file)
--- a/tools/gst-md5sum.1
+++ b/tools/gst-md5sum.1
@@ -5,22 +5,23 @@ gst\-md5sum \- get an md5sum of a GStreamer pipeline through md5sink
 \fBgst\-md5sum\fR \fI[OPTION...]\fR PARTIAL\-PIPELINE\-DESCRIPTION
 .SH "DESCRIPTION"
 .LP 
-\fIgst\-md5sum\fP is a tool that is used to get an md5 sum of 
-a basic \fIGStreamer\fP pipeline.
+\fIgst\-md5sum\fP generates MD5 checksums of the data generated by
+a GStreamer pipeline.
 
 In theory, running
 
- gst-md5sum filesrc location=music.mp3
+       gst-md5sum filesrc location=music.mp3
 
-should print out the same md5sum as
+should print out the same checksum as
 
-  md5sum music.mp3
+       md5sum music.mp3
 
-Make sure the pipeline given is a partial one, to which a sink still
-needs to be connected.
+The pipeline should be incomplete, that is, a final sink element
+should be omitted, so that gst\-md5sum can connect the pipeline to
+an md5sink element.
 
-See other docs, examples, and the source for description on how to
-create a PARTIAL\-PIPELINE\-DESCRIPTION.
+See the man page for gst\-launch or the GStreamer docuementation for 
+more information on how to create a PARTIAL\-PIPELINE\-DESCRIPTION.
 .
 .SH "OPTIONS"
 .l