Merge pull request #5308 from OpenShot/update-docs-aug-21-2023

Updating docs: Aug 21, 2023

doc/clips.rst

@@ -22,25 +22,25 @@
 Clips
 =====
 
-When media files are added to the OpenShot timeline, they are represented by a "clip", visualized as
-rounded rectangles. Clips possess various properties, affecting rendering and compositing. These
-include position, layer, scale, location, rotation, and alpha, which can be animated for
-stunning effects.
+In OpenShot, when you add project files (videos, images, and audio) to the timeline, they appear as **clips**
+represented by rounded rectangles. These clips come with different properties that influence how they're rendered
+and composited. These properties include the clip's :guilabel:`position`, :guilabel:`layer`, :guilabel:`scale`,
+:guilabel:`location`, :guilabel:`rotation`, and :guilabel:`alpha`.
 
-View a clip's properties by right-clicking and selecting "Properties" or double-clicking the clip.
-Properties appear alphabetically in the dock, with filter options available at the top. 
-See :ref:`clip_properties_ref`.
+You can examine a clip's properties by either right-clicking and selecting :guilabel:`Properties` or by double-clicking the clip.
+The properties are listed alphabetically in the Property dock, and you can use the filter options at the top to
+find specific properties. See :ref:`clip_properties_ref` for a list of all clip properties.
 
-To adjust a property:
+To **make adjustments** to a property:
 
-- Drag the slider for coarse changes.
-- Double-click to enter precise values.
-- Right/double-click for non-numerical options.
+- For **rough** changes, you can drag the slider.
+- For **precise** adjustments, double-click the property to enter exact values.
+- If the property involves **non-numerical choices**, right-click or double-click for options.
 
-Clip properties are integral to the :ref:`animation_ref` system. When you modify a clip property, a
-keyframe is generated at the current playhead position. For a property to span the entire clip,
-position the playhead at or before the clip's start before making adjustments. A convenient way to
-identify a clip's start is by utilizing the 'next/previous marker' feature on the Timeline toolbar.
+Clip properties play a vital role in the :ref:`animation_ref` system. Whenever you modify a clip property, a
+``key-frame`` is automatically created at the current playhead position. If you want a property change to apply
+throughout the entire clip, ensure the playhead is positioned at or before the clip's start, before making adjustments.
+You can easily find a clip's start by using the :guilabel:`next/previous marker` feature on the Timeline toolbar.
 
 .. image:: images/clip-overview.jpg
 
@@ -295,12 +295,12 @@ See the table below for a full list of clip properties.
    Channel Filter          Key-Frame   A number representing an audio channel to filter (clears all other channels)
    Channel Mapping         Key-Frame   A number representing an audio channel to output (only works when filtering a channel)
    Frame Number            Enum        The format to display the frame number (if any)
-   Duration                Float       The length of the clip (in seconds)
+   Duration                Float       The length of the clip (in seconds). Read-only property. This is calculated by: End - Start.
    End                     Float       The end trimming position of the clip (in seconds)
    Gravity                 Enum        The gravity of a clip determines where it snaps to its parent (details below)
    Enable Audio            Enum        An optional override to determine if this clip has audio (-1=undefined, 0=no, 1=yes)
    Enable Video            Enum        An optional override to determine if this clip has video (-1=undefined, 0=no, 1=yes)
-   ID                      String      A randomly generated GUID (globally unique identifier) assigned to each clip
+   ID                      String      A randomly generated GUID (globally unique identifier) assigned to each clip. Read-only property.
    Track                   Int         The layer which holds the clip (higher tracks are rendered on top of lower tracks)
    Location X              Key-Frame   Curve representing the relative X position in percent based on the gravity (-1 to 1)
    Location Y              Key-Frame   Curve representing the relative Y position in percent based on the gravity (-1 to 1)
@@ -357,15 +357,16 @@ The :guilabel:`Frame Number` property specifies the format in which the frame nu
 
 Duration
 """"""""
-The :guilabel:`Duration` property is a float value indicating the length of the clip in seconds.
+The :guilabel:`Duration` property is a float value indicating the length of the clip in seconds. This is a Read-only property.
+This is calculated by: End - Start. To modify duration, you must edit the :guilabel:`Start` and/or :guilabel:`End` clip properties.
 
-- **Usage Example:** Adjusting the duration of a clip to fit a specific time slot in the project.
+- **Usage Example:** Inspect the duration of a clip to ensure it fits a specific time slot in the project.
 - **Tip:** Consider using the "Duration" property for clips that need to match specific time intervals, such as dialogue or scenes.
 
 End
 """
 The :guilabel:`End` property defines the trimming point at the end of the clip in seconds, allowing you to control how much 
-of the clip is visible in the timeline.
+of the clip is visible in the timeline. Changing this property will impact the :guilabel:`Duration` clip property.
 
 - **Usage Example:** Trimming the end of a clip to align with another clip or trimming off unwanted sections of the clip.
 - **Tip:** Combine the "Start" and "End" properties to precisely control the visible portion of the clip.
@@ -405,7 +406,8 @@ Possible values: -1 (undefined), 0 (no video), 1 (video enabled).
 
 ID
 ""
-The :guilabel:`ID` property holds a randomly generated GUID (Globally Unique Identifier) assigned to each clip, ensuring its uniqueness.
+The :guilabel:`ID` property holds a randomly generated GUID (Globally Unique Identifier) assigned to each clip,
+ensuring its uniqueness. This is a Read-only property, and assigned by OpenShot when a clip is created.
 
 - **Usage Example:** Referencing specific clips within custom scripts or automation tasks.
 - **Tip:** While typically managed behind the scenes, understanding clip IDs can aid in advanced project customization.
@@ -521,6 +523,7 @@ angles in degrees, respectively. See :ref:`clip_transform_ref`.
 Start
 """""
 The :guilabel:`Start` property defines the trimming point at the beginning of the clip in seconds.
+Changing this property will impact the :guilabel:`Duration` clip property.
 
 - **Usage Example:** Removing the initial portion of a clip to focus on a specific scene or moment.
 - **Tip:** Utilize the "Start" property in combination with the "End" property for precise clip trimming.