[xiph-commits] r12716 - trunk/ezstream/doc

[moritz at svn.xiph.org]

Author: moritz
Date: 2007-03-10 16:02:20 -0800 (Sat, 10 Mar 2007)
New Revision: 12716

Modified:
   trunk/ezstream/doc/ezstream.1.in
Log:
Formatting improvements, and some minor rewording.


Modified: trunk/ezstream/doc/ezstream.1.in
===================================================================
--- trunk/ezstream/doc/ezstream.1.in	2007-03-10 23:36:52 UTC (rev 12715)
+++ trunk/ezstream/doc/ezstream.1.in	2007-03-11 00:02:20 UTC (rev 12716)
@@ -75,7 +75,8 @@
 restarts the current track when streaming a single file.
 .It Cd SIGUSR2
 Triggers rereading of metadata for the stream by running the program or script
-specified in \&<metadata_progname/\&>
+specified in
+.Li \&<metadata_progname/\&>
 .Pq see below.
 This is the only meaningful signal when streaming from standard input.
 .El
@@ -92,9 +93,9 @@
 configuration file.
 .Pp
 Each element in the configuration file consists of a
-.Li start tag ,
+.Em start tag ,
 its content and an
-.Li end tag .
+.Em end tag .
 For example:
 .Pp
 .Dl \&<filename\&>playlist.m3u<\&/filename\&>
@@ -114,8 +115,9 @@
 It contains all other configuration elements.
 .El
 .Ss Global configuration elements
-Each of the global configuration elements have the \&<ezstream/\&> element as
-their parent.
+Each of the global configuration elements have the
+.Li \&<ezstream/\&>
+element as their parent.
 .Bl -tag -width -Ds
 .It Sy \&<url\ /\&>
 .Pq Mandatory.
@@ -172,13 +174,14 @@
 Set to
 .Sy 1
 .Pq one
-to indicate that the file in \&<filename/\&> is actually an executable program
-or script.
+to indicate that the file in
+.Li \&<filename/\&>
+is actually an executable program or script.
 If set to
 .Sy 0
 .Pq zero ,
-\&<filename/\&> content is assumed to be a media file, playlist file or the
-keyword
+.Li \&<filename/\&>
+content is assumed to be a media file, playlist file or the keyword
 .Pa stdin
 .Pq the default .
 .Pp
@@ -190,12 +193,17 @@
 Set to
 .Sy 1
 .Pq one
-to randomly shuffle the entries of the playlist specified in \&<filename/\&>.
+to randomly shuffle the entries of the playlist specified in
+.Li \&<filename/\&> .
 Files are played sequentially if set to
 .Sy 0
 .Pq zero
-or when the \&<shuffle/\&> element is absent.
-This option will be ignored if \&<playlist_program/\&> is set to 1
+or when the
+.Li \&<shuffle/\&>
+element is absent.
+This option will be ignored if
+.Li \&<playlist_program/\&>
+is set to 1
 .Pq one.
 .It Sy \&<metadata_progname\ /\&>
 .Pq Optional.
@@ -207,8 +215,10 @@
 .Sy SIGUSR2
 signal is received.
 .Pp
-If the \&<metadata_progname/\&> element is present in the configuration, no
-attempts will be made to read metadata from files that are being streamed.
+If the
+.Li \&<metadata_progname/\&>
+element is present in the configuration, no attempts will be made to read
+metadata from files that are being streamed.
 If this behavior is not desired, it should be removed or commented out in the
 configuration file.
 .Pp
@@ -218,9 +228,9 @@
 .It Sy \&<metadata_format\ /\&>
 .Pq Optional.
 Set the format of the string that should be used for the
-.Sq @M@
+.Sq Li @M@
 placeholder when setting metadata with an external program or script via
-\&<metadata_progname/\&>.
+.Li \&<metadata_progname/\&> .
 .Pp
 See the
 .Sy METADATA
@@ -230,7 +240,9 @@
 Set to
 .Sy 1
 .Pq one
-in order to stream the content of \&<filename/\&> only once, and to
+in order to stream the content of
+.Li \&<filename/\&>
+only once, and to
 .Sy 0
 .Pq zero
 for continuous streaming
@@ -292,14 +304,17 @@
 .Sy 0
 .Pq zero ,
 the Icecast server will not submit this stream to a YP directory, which is also
-the default if the \&<svrinfopublic/\&> element is absent.
+the default if the
+.Li \&<svrinfopublic/\&>
+element is absent.
 .It Sy \&<reencode\ /\&>
 .Pq Optional.
 Element that contains child elements, which specify if and how reencoding
 should be done.
 .El
 .Ss Reencoding settings
-Each of the reencoding configuration elements have the \&<reencode/\&>
+Each of the reencoding configuration elements have the
+.Li \&<reencode/\&>
 element as their parent.
 .Bl -tag -width -Ds
 .It Sy \&<enable\ /\&>
@@ -310,22 +325,27 @@
 If set to
 .Sy 0
 .Pq zero ,
-no reencoding will be done, which is also the default if the \&<enable/\&>
+no reencoding will be done, which is also the default if the
+.Li \&<enable/\&>
 element is absent.
 .It Sy \&<encdec\ /\&>
 Element that contains child elements, which specify how to decode and encode
 a certain media file format for streaming.
-Each format is described by a separate \&<encdec/\&> element.
+Each format is described by a separate
+.Li \&<encdec/\&>
+element.
 .El
 .Ss Decoder/Encoder settings
-Each of the decoder/encoder configuration elements have the \&<encdec/\&>
+Each of the decoder/encoder configuration elements have the
+.Li \&<encdec/\&>
 element as their parent.
 .Bl -tag -width -Ds
 .It Sy \&<format\ /\&>
 This element is used by
 .Nm
 to find the appropriate encoder for the output stream format specified in the
-\&<format/\&> element inside the global configuration.
+.Li \&<format/\&>
+element inside the global configuration.
 For consistency reasons, it is recommended that this element is always
 supplied, even for currently unsupported output formats, with content such as
 .Sy VORBIS ,
@@ -351,12 +371,15 @@
 During runtime, the placeholder
 .Sq Li @T@
 is replaced with the name of the media file, as it is specified in the
-\&<filename/\&> element or contained in a playlist file.
+.Li \&<filename/\&>
+element or contained in a playlist file.
 It should always be enclosed in quotes, to prevent problems with filenames that
 contain whitespaces.
 .Pp
-Metadata placeholders can be used in the \&<decode/\&> element as well, for
-combined de-/encoder programs that produce streamable data.
+Metadata placeholders can be used in the
+.Li \&<decode/\&>
+element as well, for combined de-/encoder programs that produce streamable
+data.
 See the
 .Sy METADATA
 section for details on how metadata is handled by
@@ -371,7 +394,9 @@
 Set the command to encode raw data, received from standard input, to the
 specified stream format.
 .Pp
-Metadata placeholders can be used in the \&<encode/\&> element.
+Metadata placeholders can be used in the
+.Li \&<encode/\&>
+element.
 For details about using metadata in
 .Nm ,
 see below in the
@@ -410,7 +435,9 @@
 The program should not return an empty line unless
 .Nm
 is supposed to know that the end of the playlist has been reached.
-This is significant when the \&<stream_once/\&> option is enabled.
+This is significant when the
+.Li \&<stream_once/\&>
+option is enabled.
 .El
 .Ss Metadata Programs
 .Bl -dash -compact
@@ -424,12 +451,12 @@
 complete string that should be used for metadata.
 .It
 When called with the command line parameter
-.Qq artist ,
+.Qq Li artist ,
 the program should return only the artist information of the metadata.
 .Pq Optional.
 .It
 When called with the command line parameter
-.Qq title ,
+.Qq Li title ,
 the program should return only the title information of the metadata.
 .Pq Optional.
 .El
@@ -445,26 +472,42 @@
 .Bl -tag -width -Ds
 .It Sy @T@
 Replaced with the media file name.
-Required in \&<decode/\&> and is available in \&<metadata_format/\&>.
+Required in
+.Li \&<decode/\&>
+and is available in
+.Li \&<metadata_format/\&> .
 .It Sy @M@
 Replaced with a metadata string.
 See below for a detailed explanation.
-Available in \&<decode/\&> and \&<encode/\&>.
+Available in
+.Li \&<decode/\&>
+and
+.Li \&<encode/\&> .
 .It Sy @a@
 Replaced with the artist information.
-Available in \&<decode/\&>, \&<encode/\&> and \&<metadata_format/\&>.
+Available in
+.Li \&<decode/\&> ,
+.Li \&<encode/\&>
+and
+.Li \&<metadata_format/\&> .
 .It Sy @t@
 Replaced with the title information.
-Available in \&<decode/\&>, \&<encode/\&> and \&<metadata_format/\&>.
+Available in
+.Li \&<decode/\&> ,
+.Li \&<encode/\&>
+and
+.Li \&<metadata_format/\&> .
 .It Sy @s@
-Replaced with the string returned by \&<metadata_progname/\&> when called
-without any command line parameters.
-Available only in \&<metadata_format/\&>.
+Replaced with the string returned by
+.Li \&<metadata_progname/\&>
+when called without any command line parameters.
+Available only in
+.Li \&<metadata_format/\&> .
 .El
 .Ss The @M@ Placeholder
 While all other placeholders are simply replaced with whatever data they are
 associated with,
-.Sq @M@
+.Sq Li @M@
 is context-sensitive.
 The logic used by
 .Nm
@@ -484,15 +527,15 @@
 .Ed
 .Pp
 The generated metadata string for
-.Sq @M@
+.Sq Li @M@
 is of the format
-.Dq Artist - Title ,
+.Dq Em Artist - Title ,
 if both artist and title information is available.
 If one of the two is missing, the available one is displayed without a leading
 or trailing dash, e.g. just
-.Dq Artist .
-If neither artist nor title are available, the name of the media file, without
-its file extension, is used.
+.Dq Em Artist .
+If neither artist nor title are available, the name of the media file \(em
+without its file extension \(em is used.
 .Ss Metadata Caveats
 It is possible to generate strange results with odd combinations of
 placeholders, external metadata programs and updates during runtime via
@@ -508,7 +551,7 @@
 which means that anything set with the
 .Sy SIGUSR2
 feature will continue to end up entirely in the
-.Qq Title
+.Qq Em Title
 field of a stream.
 .Sh FILES
 .Bl -tag -width "!!EXAMPLES_DIR!!" -compact