2022-05-11 Fred Gleason <fredg@paravelsystems.com>

* Updated the 'Content Management with RDLibrary' chapter of
	the Operations Guide.

Signed-off-by: Fred Gleason <fredg@paravelsystems.com>

ChangeLog

@@ -23068,3 +23068,6 @@
 2022-05-11 Fred Gleason <fredg@paravelsystems.com>
 	* Fixed a regression in rdlibrary(1) that caused the disk free space
 	gauge to be disabled.
+2022-05-11 Fred Gleason <fredg@paravelsystems.com>
+	* Updated the 'Content Management with RDLibrary' chapter of
+	the Operations Guide.

docs/opsguide/Makefile.am

@@ -2,7 +2,7 @@
 ##
 ## docs/opsguide/automake.am for Rivendell
 ##
-## (C) Copyright 2017-2020 Fred Gleason <fredg@paravelsystems.com>
+## (C) Copyright 2017-2022 Fred Gleason <fredg@paravelsystems.com>
 ##
 ##   This program is free software; you can redistribute it and/or modify
 ##   it under the terms of the GNU General Public License version 2 as
@@ -252,6 +252,7 @@ OPSGUIDE_IMAGES = rdadmin.audio_resource_information_dialog.png\
                   rdlibrary.edit_cut_info_dialog.png\
                   rdlibrary.edit_macro_cart_dialog.png\
                   rdlibrary.edit_marker_dialog.png\
+                  rdlibrary.edit_marker_dialog.marker_menu.png\
                   rdlibrary.import_export_dialog.png\
                   rdlibrary.rdlibrary_screenshot.png\
                   rdlibrary.rip_disk_dialog.png\

docs/opsguide/rdlibrary.xml

@@ -1,4 +1,4 @@
-<chapter xmlns="http://docbook.org/ns/docbook" xml:id="chapter.rdlibrary">
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chapter.rdlibrary">
   <title>Content Management with RDLibrary</title>
   <sect1 xml:id="sect.rdlibrary.the_rivendell_library_structure_and_rdlibrary">
     <title>The Rivendell Library Structure and RDLibrary</title>
@@ -6,13 +6,15 @@
       <title>Carts</title>
       <para>
 	The Rivendell Library consists of a set of objects called
-	<emphasis>carts</emphasis>.
+	<emphasis>carts</emphasis> (short for "cartridge", a nod to the days
-	A cart is a data container that holds either one or more pieces
+	when audio material for radio broadcast was commonly loaded to and
-	of audio (called an <emphasis>audio cart</emphasis>), or macro
+	played from physical cartridges).
+	A Rivendell cart is a data container that holds either one or more
+	pieces of audio (called an <emphasis>audio cart</emphasis>), or macro
 	commands to the system
-	(called a <emphasis>macro cart</emphasis>). The cart is the
+	(called a <emphasis>macro cart</emphasis>). Carts are the
 	fundamental schedule
-	building block in Rivendell, in that it is the smallest object or
+	building block in Rivendell, in that they are the smallest object or
 	'atom' that the outside world (like a traffic or music scheduler)
 	can see.
       </para>
@@ -34,13 +36,22 @@
 	A number of important attributes of carts can be seen from this
 	illustration.  First is the cart's number.  Each cart in the Library
 	gets assigned a unique number when it is created.  This number can
-	range between 000001 and 999999, and is the primary 'handle' by which
+	range between 1 and 999999, and is the primary 'handle' by which
 	both Rivendell and external systems (like traffic or music schedulers)
 	refer to the cart.  Very often, sites have specific rules concerning
 	which types of audio (commercials, promos, music, etc) and macros get
 	assigned which numbers.  We'll cover this area in some detail when
 	we discuss groups.
       </para>
+      <note>
+	Cart numbers in Rivendell are commonly displayed so that they
+	always have six digits, even if that means adding leading zeros
+	to the numbers --e.g. cart '123' will be displayed as '000123'.
+	This convention is used as a visual reminder that the value in
+	question is a Rivendell cart number, but it is perfectly valid to use
+	numbers without the leading zeros when inputting cart numbers into
+	Rivendell.
+      </note>
       <para>
 	Immediately to the left of the cart number is an icon indicating
 	the type of cart. Just to the right of the cart number is the
@@ -95,8 +106,7 @@
 		the audio.  Care is needed when implementing timescaling
 		within a facility, as there are limits to how much the
 		length can be altered, while only certain types of audio
-		adapters support it at all.  See the Rivendell Technical
+		adapters support it at all.
-		Guide for more information.
 	      </para>
 	    </listitem>
 	  </varlistentry>
@@ -105,8 +115,21 @@
 	    <listitem>
 	      <para>
 		This is a pull down menu by which the group ownership for
-		the cart can be set.  The system administrator configures
+		the cart can be set. Every cart in Rivendell belongs to
-		the list of available groups for each user in RDAdmin.
+		precisely one group. The system administrator configures
+		the list of available groups for each user in RDAdmin, and
+		may also define limits to which cart numbers are allowed
+		to belong to particular groups.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Usage</term>
+	    <listitem>
+	      <para>
+		This defines the use to which the material is put. It
+		is included in records generated by the ASCAP/BMI Electronic
+		Music Report.
 	      </para>
 	    </listitem>
 	  </varlistentry>
@@ -139,7 +162,7 @@
       </para>
       <variablelist>
 	<varlistentry>
-	  <term><computeroutput>WT</computeroutput></term>
+	  <term><computeroutput>Wt</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The <emphasis>weighting</emphasis> value for the cut. see
@@ -148,7 +171,7 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>ORDER</computeroutput></term>
+	  <term><computeroutput>Order</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The <emphasis>order</emphasis> value for the cut. see
@@ -157,17 +180,17 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>DESCRIPTION</computeroutput></term>
+	  <term><computeroutput>Description</computeroutput></term>
 	  <listitem>
 	    <para>
-	      n arbitrary name, assignable by the user as an aid in keeping
+	      An arbitrary string, assignable by the user as an aid in keeping
 	      track of the content, it is roughly analogous to the 'Title'
 	      field in the cart label.
 	    </para>
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>LENGTH</computeroutput></term>
+	  <term><computeroutput>Length</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The actual, measured play out length of the cut audio.
@@ -176,7 +199,7 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>LAST PLAYED</computeroutput></term>
+	  <term><computeroutput>Last Played</computeroutput></term>
 	  <listitem>
 	    <para>
 	      he last date and time that the cut was aired by one of the
@@ -185,7 +208,7 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput># OF PLAYS</computeroutput></term>
+	  <term><computeroutput># of Plays</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The total number of times the cut has been aired by the
@@ -194,7 +217,7 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>ORIGIN</computeroutput></term>
+	  <term><computeroutput>Origin</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The name of the host upon which the audio in the cut was last
@@ -203,16 +226,16 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>OUTCUE</computeroutput></term>
+	  <term><computeroutput>Outcue</computeroutput></term>
 	  <listitem>
 	    <para>
 	      A user settable field. This line shows up in the RDAirPlay
-	      log when the cut is played.
+	      log display when the cut is played.
 	    </para>
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>START DATE</computeroutput></term>
+	  <term><computeroutput>Start Date</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The effective start date/time of the cut.
@@ -220,7 +243,7 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>END DATE</computeroutput></term>
+	  <term><computeroutput>End Date</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The effective end date/time of the cut.
@@ -228,7 +251,7 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>START DAYPART</computeroutput></term>
+	  <term><computeroutput>Start Daypart</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The start time of the cut's daypart.
@@ -236,7 +259,7 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>END DAYPART</computeroutput></term>
+	  <term><computeroutput>End Daypart</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The start time of the cut's daypart.
@@ -244,7 +267,7 @@
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term><computeroutput>NAME</computeroutput></term>
+	  <term><computeroutput>Name</computeroutput></term>
 	  <listitem>
 	    <para>
 	      The internal CUTNAME of the cut as used in Rivendell's
@@ -266,11 +289,11 @@
 	<title>Multiple Cuts in a Cart</title>
 	<para>
 	  What happens when more than one cut is placed into a cart? The
-	  answer, in a word, is <emphasis>rotation</emphasis>. Rotation is
+	  default answer, in a word, is <emphasis>rotation</emphasis>.
-	  the ability to
+	  Rotation is the ability to
 	  schedule a single cart in a log, but to have that cart play out
-	  different material at different times. This capability has a
+	  different material at different times. This capability has
-	  myriad of uses.  One of the simplest, common in commercial radio
+	  myriad uses. One of the simplest, common in commercial radio
 	  facilities, is to allow multiple versions of a spot to be placed
 	  into the system, while still allowing the traffic department to
 	  have to track and schedule only one cart number. A more
@@ -330,7 +353,7 @@
 	</para>
 	<para>
 	  While not strictly a dayparting parameter, the
-	  <computeroutput>WEIGHT</computeroutput> setting of a cut can
+	  <computeroutput>Weight</computeroutput> setting of a cut can
 	  strongly influence
 	  the order (and hence placement) of when a particular cut will play.
 	  The weight value of each cut in a cart consistutes the numerator
@@ -419,11 +442,11 @@
 	    </varlistentry>
 	  </variablelist>
 	</para>
-	<para>
+	<caution>
 	  It's important to remember that the color displayed for each
 	  event indicates playability <emphasis>at the instant that the event
 	  is being viewed</emphasis>.
-	</para>
+	</caution>
       </sect3>
       <sect3 xml:id="sect.rdlibrary.recording_and_auditioning_a_cut_in_the_record_dialog">
 	<title>Recording and Auditioning a Cut in the Record Dialog</title>
@@ -689,7 +712,7 @@
       selecting it and then touching the
       <computeroutput>Delete</computeroutput> button, or modified by
       touching the <computeroutput>Edit</computeroutput> button. The RML
-      can be tested, eight line-by-line
+      can be tested, either line-by-line
       or as a whole by touching the <computeroutput>Run Line</computeroutput>
       or <computeroutput>Run Cart</computeroutput> button
       respectively. It is also possible to
@@ -729,17 +752,17 @@
 	The order in which carts are displayed in the cart list can be
 	changed by simply clicking on the header of the column by which
 	you want them sorted by. By default, the carts are sorted by Cart
-	Number.  To instead sort them alphabetically by Title, simply click
+	Number. To sort them alphabetically by Title instead, simply click
-	the <computeroutput>TITLE</computeroutput> header once.
+	the <computeroutput>Title</computeroutput> header once.
-	To sort them by Title in reverse –i.e.
+	To sort them by Title in reverse --i.e.
-	from 'Z' to 'A' – click the <computeroutput>TITLE</computeroutput>
+	from 'Z' to 'A' – click the <computeroutput>Title</computeroutput>
 	header once again.  Clicking the
-	<computeroutput>TITLE</computeroutput> header a third time restores
+	<computeroutput>Title</computeroutput> header a third time restores
 	the sort to normal 'A' to 'Z' again. And so on for all of the columns
 	in the cart list – it's
 	possible to sort the Library by
-	<computeroutput>ARTIST</computeroutput>,
+	<computeroutput>Artist</computeroutput>,
-	<computeroutput>LENGTH</computeroutput>, or any other
+	<computeroutput>Length</computeroutput>, or any other
 	parameter shown in the cart list.
       </para>
     </sect2>
@@ -834,7 +857,7 @@
 	Markers are set in the Edit Markers Dialog.
 	To access the Dialog, open an audio cart, select the cut to open
 	on the cut list and then touch the
-	<computeroutput>Edit</computeroutput> button.
+	<computeroutput>Edit Markers</computeroutput> button.
       </para>
       <para>
 	The Dialog is divided into three areas:  the waveform area in the
@@ -846,9 +869,10 @@
 	<computeroutput>Pause</computeroutput>, 
 	<computeroutput>Stop</computeroutput> and
 	<computeroutput>Loop</computeroutput> buttons along with an
-	audio meter;
+	audio meter and marker position readouts,
-	and the marker button area in the lower third of the window,
+	and the bottom section containing the usual
-	consisting of controls for selecting and positioning markers.  
+	<computeroutput>OK</computeroutput> and
+	<computeroutput>Cancel</computeroutput> buttons.
       </para>
       <para>
 	<mediaobject>
@@ -875,151 +899,118 @@
 	waveform to indicate where play out should start and then clicking
 	the left-hand <computeroutput>Play</computeroutput> button,
 	causing play out to start from the
-	selected position, or by clicking the right-hand 
+	selected position, or by clicking the center
 	<computeroutput>Play</computeroutput> button, which
-	will cause play out to start from the Start Marker (just as it
+	will cause play out to start from the currently selected start
-	would in RDAirPlay).  Clicking the
+	marker.
-	<computeroutput>Pause</computeroutput> button while playing will
-	cause audio to stop and the play out cursor (a thin vertical black
-	line in the waveform area) to freeze at its current position, while
-	pressing the <computeroutput>Stop</computeroutput> button will stop
-	the audio while resetting the
-	play out cursor to the position it was in when
-	<computeroutput>Play</computeroutput> was started.
 	Clicking the <computeroutput>Loop</computeroutput> button will
 	cause the audio to play out
 	continuously, looping from end back to start, until either the
 	<computeroutput>Stop</computeroutput>, 
-	<computeroutput>Pause</computeroutput>, 
 	<computeroutput>Save</computeroutput> or
 	<computeroutput>Cancel</computeroutput> buttons are clicked.
       </para>
       <para>
-	To set a marker, click on the corresponding marker button and then
+	All cuts have <computeroutput>Cut</computeroutput> markers, used
-	left-click on the waveform area to indicate where on the audio
+	to indicate the absolute start and end of the cut when played on-air.
-	the marker should be placed.  (NOTE:  With the exception of the
+	To adjust the position of the markers, position the mouse cursor
-	FadeUp and FadeDown markers, all markers in Rivendell are assigned
+	over one of the arrows on the marker, press and hold the left-hand
-	in pairs. For example, placing a TalkStart marker will also cause
+	mouse button and drag it to the desired location. The marker's
-	a TalkEnd marker to be placed.)  Markers that have already been
+	arrows will become larger to indicate that the marker has been
-	placed can be moved by selecting the appropriate marker button and
+	selected.
-	then dragging the marker to the desired location.  It's also possible
-	to specify the position of a marker in the form of hh:mm:ss.s
-	(relative to time after the Start marker) by entering the desired
-	value next to a selected marker button.  It is also possible to
-	remove a set of markers that have already been placed, either by
-	accessing the marker menu by doing a right-click on the waveform
-	display, or by touching the
-	<computeroutput>Remove Marker</computeroutput> button and then touch
-	the marker button corresponding to the marker to be removed.
-	(NOTE: the exceptions to this are the Start / End markers, which
-	are always present and hence cannot be removed.)
       </para>
-      <table xml:id="table.rdlibrary.marker_types" frame="all">
-	<title>Rivendell Marker Types</title>
-	<tgroup cols="3" align="left" colsep="1" rowsep="1">
-	  <colspec colname="Marker Type" />
-	  <colspec colname="Function" />
-	  <colspec colname="Color" />
-	  <thead>
-	    <row>
-	      <entry>
-		Marker Type
-	      </entry>
-	      <entry>
-		Function
-	      </entry>
-	      <entry>
-		Color
-	      </entry>
-	    </row>
-	  </thead>
-	  <tbody>
-	    <row>
-	      <entry>
-		Start / Stop
-	      </entry>
-	      <entry>
-		Indicates start and end points of audio.
-	      </entry>
-	      <entry>
-		RED
-	      </entry>
-	    </row>
-	    <row>
-	      <entry>
-		TalkStart / Talk Stop
-	      </entry>
-	      <entry>
-		Indicates point to start and stop the Talk Counter in RDAirPlay.
-	      </entry>
-	      <entry>
-		BLUE
-	      </entry>
-	    </row>
-	    <row>
-	      <entry>
-		SegueStart / SegueEnd
-	      </entry>
-	      <entry>
-		Indicates the start and end of the audio overlap during
-		Segue transitions in RDAirPlay.
-	      </entry>
-	      <entry>
-		CYAN
-	      </entry>
-	    </row>
-	    <row>
-	      <entry>
-		HookStart / HookEnd
-	      </entry>
-	      <entry>
-		Indicates &quot;highlighted&quot; audio, used by button
-		panels and RDCartSlots when placed in Hook Mode.
-	      </entry>
-	      <entry>
-		VIOLET
-	      </entry>
-	    </row>
-	    <row>
-	      <entry>
-		FadeUp
-	      </entry>
-	      <entry>
-		Indicates the point at which audio should be faded up to
-		full level after starting in RDAirPlay.
-	      </entry>
-	      <entry>
-		YELLOW
-	      </entry>
-	    </row>
-	    <row>
-	      <entry>
-		FadeDown
-	      </entry>
-	      <entry>
-		Indicates the point at which audio should start fading
-		down to off before ending in RDAirPlay.
-	      </entry>
-	      <entry>
-		YELLOW
-	      </entry>
-	    </row>
-	  </tbody>
-	</tgroup>
-      </table>
       <para>
-	As an aid for accurately setting the Start and End markers, it's
+	Additional markers can be set as follows:
-	possible to use the <computeroutput>Trim Start</computeroutput>
+      </para>
-	and <computeroutput>Trim End</computeroutput> buttons to automatically
+      <variablelist>
-	set the markers to the first and last instances of the level
+	<varlistentry>
-	specified by the <computeroutput>Threshold</computeroutput> field,
+	  <term>
-	respectively.
+	    <computeroutput>Fade Down</computeroutput>
+	  </term>
+	  <listitem>
+	    <para>
+	      Indicates the point in the cut play-out to begin a steady
+	      fade down that will continue until the end
+	      <computeroutput>Cut</computeroutput> marker.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    <computeroutput>Fade Up</computeroutput>
+	  </term>
+	  <listitem>
+	    <para>
+	      Indicates the point in the cut play-out to end a steady
+	      fade up that starts at the start
+	      <computeroutput>Cut</computeroutput> marker.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    <computeroutput>Hook</computeroutput>
+	  </term>
+	  <listitem>
+	    <para>
+	      Indicates the portion of the cut to be played by a
+	      sound panel when in <computeroutput>Hook</computeroutput>
+	      mode.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    <computeroutput>Segue</computeroutput>
+	  </term>
+	  <listitem>
+	    <para>
+	      Indicates the portion of the cut to be 
+	      overlapped with audio from the following log
+	      event when used with a <computeroutput>SEGUE</computeroutput>
+	      transition in
+	      <command>rdairplay</command><manvolnum>1</manvolnum>.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    <computeroutput>Talk</computeroutput>
+	  </term>
+	  <listitem>
+	    <para>
+	      Indicates the start and end points of the &quot;Pie Widget&quot;
+	      talk timer when the cut is played in
+	      <command>rdairplay</command><manvolnum>1</manvolnum>.
+	    </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+      <para>
+	To add a marker, position the mouse cursor on the waveform, press
+	the right-hand button and select the desired marker from the pop-up
+	menu. Once added, a marker can be repositioned in the usual way.
+      </para>
+      <para>
+	To delete a marker, position the mouse cursor on one of the marker's 
+	arrows, press the right-hand button and select
+	<computeroutput>Delete Marker</computeroutput> from the pop-up menu.
+      </para>
+      <para>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata align="center" fileref="rdlibrary.edit_marker_dialog.marker_menu.png" scale="50"/>
+	  </imageobject>
+	  <caption>
+	    <para>The Marker Menu</para>
+	  </caption>
+	</mediaobject>
       </para>
     </sect2>
     <sect2 xml:id="sect.rdlibrary.copying_and_pasting_audio_from_cut_to_cut">
       <title>Copying and Pasting Audio from Cut to Cut</title>
       <para>
-	It's possible to make copies of existing an audio cut on the system
+	It's possible to make copies of an existing audio cut on the system
 	by opening up the cut's parent cart in the Edit Cart Dialog,
 	selecting it on the cut list and clicking the
 	<computeroutput>Copy</computeroutput> button. To
@@ -1036,7 +1027,11 @@
       <computeroutput>Reports</computeroutput>
       button on the main RDLibrary screen and then selecting the desired
       report and touching the <computeroutput>Generate</computeroutput>
-      button. The following reports are available:
+      button. The contents of the resulting report will be filtered
+      according to RDLibrary's the current search parameters.
+    </para>
+    <para>
+      The following reports are available:
     </para>
     <sect2 xml:id="sect.rdlibrary.the_cart_report">
       <title>The Cart Report</title>