[documentation/digikam-doc/sphinx] /: add versions section

Gilles Caulier null at kde.org
Sat Dec 17 18:20:45 GMT 2022


Git commit a6328d8cf8c584e7cadcbb28eca3d12b27cceac2 by Gilles Caulier.
Committed on 17/12/2022 at 18:20.
Pushed by cgilles into branch 'sphinx'.

add versions section

D  +0    -138  attic/digikam/using-sidebar-captions.docbook
D  +0    -46   attic/digikam/using-sidebar-versions.docbook
M  +4    -0    index.rst
M  +1    -0    right_sidebar.rst
R  +-    --    right_sidebar/images/using-sidebar-versionsclist.png [from: attic/digikam/using-sidebar-versions-clist.png - 100% similarity]
R  +-    --    right_sidebar/images/using-sidebar-versionstree.png [from: attic/digikam/using-sidebar-versions-tree.png - 100% similarity]
A  +28   -0    right_sidebar/versions_view.rst

https://invent.kde.org/documentation/digikam-doc/commit/a6328d8cf8c584e7cadcbb28eca3d12b27cceac2

diff --git a/attic/digikam/using-sidebar-captions.docbook b/attic/digikam/using-sidebar-captions.docbook
deleted file mode 100644
index 76df3c1..0000000
--- a/attic/digikam/using-sidebar-captions.docbook
+++ /dev/null
@@ -1,138 +0,0 @@
-<sect2 id="using-sidebar-captions">
-    <title>Captions</title>
-
-    <sect3>
-    <title>Introduction</title>
-
-        <para>
-            This sidebar tab serves to apply and edit image attributes like captions, rating, date and tags. The attributes are stored in the associated database, in the IPTC and EXIF data fields and become part of the image. All attributes are accessible in one sidebar view as shown in the screenshot below. During image reading the order of priority is a) database b) IPTC and c) EXIF. So if there is a discrepancy between any of the three, this priority will take effect and a synchronization will take place. This sidebar has a first-previous-next-last arrow navigator field on top if shown in the main application.
-        </para>
-
-        <example>
-            <title>sidebar Comments & Tags example</title>
-            <screenshot>
-                <screeninfo>sidebar Comments & Tags Example</screeninfo>
-                <mediaobject><imageobject>
-                    <imagedata fileref="&path;using-sidebar-captions.png" format="PNG" />
-                </imageobject></mediaobject>
-            </screenshot>
-        </example>
-
-    </sect3>
-
-    <sect3>
-        <title>Comment View</title>
-
-        <para>
-            The caption view can be used to type or paste in a caption of unlimited size (see note below). The text is UTF-8 compatible, meaning that all special characters are allowed. The captions are copied to EXIF and IPTC fields to be used by other applications.
-        </para>
-
-        <caution><para>
-            IPTC data only supports ASCII characters and is limited to 2000 characters (old American norm). All texts will be truncated after 2000 chars, and special characters will be malformed. If you intend to use the IPTC caption field in other applications you should be compliant with these restrictions.
-        </para></caution>
-
-        <para>
-            After commenting, either choose the <guibutton>Apply</guibutton> button or go straight to the next image, the captions will be saved.
-        </para>
-
-        <para>
-            Next to the Apply button there is the <guibutton>More</guibutton> button. From it you can either choose to read metadata from the selected file to the database, or the other way around, to write metadata to the files (the latter take place anyway if you chose a metadata setting so that all metadata is always saved to the images).
-        </para>
-
-    </sect3>
-
-    <sect3>
-
-        <title>Date & Time</title>
-
-        <para>
-            In the Date & Time section, which reflects the time of taking the photograph, you can change all values. From the date combo-box a calendar opens, and the time setting spin-box can also be written by directly typing the time. The dating is copied to the EXIF 'Date and Time' field. If you need to change a number of images for their creating time & date, there is a more comfortable method available in Batch Queue Manager. This latter option can be found under <menuchoice><guimenuitem>Image</guimenuitem><guimenuitem>Adjust time & date...</guimenuitem></menuchoice>. Select the images to be changed in the main view and call the tool.
-        </para>
-
-    </sect3>
-
-    <sect3>
-    <title>Rating</title>
-
-    <para>
-        The Rating section displays a 0...5 star rating scheme that can be used in searches and sort orders. It can be applied by a single mouse click to the 5 stars in the sidebar or with a keyboard short-cut <keycombo>&Ctrl;<keycap>0...5</keycap></keycombo>. The rating from the sidebar is always applied to one image at a time. To rate a number of images, select them and pop-up the context menu (click with the &RMB;) to apply a common rating.
-    </para>
-
-    <para>
-        The rating is then transcribed into the IPTC 'urgency' data field. The transcoding follows the scheme in this table:
-    </para>
-
-    <informaltable><tgroup cols="2">
-
-        <thead><row>
-            <entry>&digikam; Rating</entry>
-            <entry>IPTC Urgency</entry>
-            </row></thead>
-
-            <tbody>
-                <row>   <entry>-</entry>         <entry>8</entry>      </row>
-
-                <row>   <entry>*</entry>         <entry>7</entry>      </row>
-
-                <row>   <entry>*</entry>         <entry>6</entry>      </row>
-
-                <row>   <entry>**</entry>        <entry>5</entry>      </row>
-
-                <row>   <entry>***</entry>       <entry>4</entry>      </row>
-
-                <row>   <entry>****</entry>      <entry>3</entry>      </row>
-
-                <row>   <entry>****</entry>      <entry>2</entry>      </row>
-
-                <row>   <entry>*****</entry>     <entry>1</entry>      </row>
-            </tbody>
-
-        </tgroup></informaltable>
-
-    </sect3>
-
-    <sect3 id="using-sidebar-tags">
-    <title>Tag Tree</title>
-
-        <para>
-            The tag view shows an adaptive filter tag search box, the tag tree and a combo-box containing the tags previously applied in this &digikam; session.
-        </para>
-
-        <para>
-            The tag tree will be adapted dynamically as a function of the search word as you type into the box. So it is easy to quickly reduce the number of possibilities when searching for a tag. Of course, this feature is only useful if you have many tags.
-        </para>
-
-        <para>
-            The combo-box at the bottom is another ergonomic feature for easy tagging of an image series. As you apply different tags they will be memorized in this box for quick access.
-        </para>
-
-        <para>
-            Otherwise tags are simply applied by checking the respective boxes in the tree. All tags of an image are transcribed into the IPTC 'keyword' data field.
-        </para>
-
-        <note><para>
-            In case you have selected a number of images in the main view and you check a tag in the tag tree, this one is only applied to the highlighted image, and not to the whole selection. If you want to tag selections, refer to the <link linkend="using-sidebar-filters">Filters</link> section.
-        </para></note>
-
-    </sect3>
-
-    <sect3>
-        <title>Information View</title>
-
-            <para>
-                TODO
-            </para>
-
-    </sect3>
-
-</sect2>
-
-<!--
-Local Variables:
-mode: sgml
-sgml-minimize-attributes:nil
-sgml-general-insert-case:lower
-sgml-indent-step:0
-sgml-indent-data:nil
-End:
--->
diff --git a/attic/digikam/using-sidebar-versions.docbook b/attic/digikam/using-sidebar-versions.docbook
deleted file mode 100644
index 3a79437..0000000
--- a/attic/digikam/using-sidebar-versions.docbook
+++ /dev/null
@@ -1,46 +0,0 @@
-<sect2 id="using-sidebar-versions">
-    <title>Versions view</title>
-
-    <para>
-        The <guilabel>Versions</guilabel> tab shows the history and the saved versions of a photograph. With the three buttons in the top right corner you can choose between a simple list of the saved versions, a tree view and a combined list that shows the versions together with the actions performed with the selected photograph.
-    </para>
-
-    <para>
-        <inlinemediaobject>
-            <imageobject>
-                <imagedata fileref="&path;using-sidebar-versions-tree.png" format="PNG" />
-            </imageobject>
-        </inlinemediaobject>
-    </para>
-    
-    <para>
-        The tree view shows the parent and child versions of the selected image. Here the second and the fifth version derive directly from the original image, the third and forth version are children of the second version.
-    </para>
-    
-    <para>
-        <inlinemediaobject>
-            <imageobject>
-                <imagedata fileref="&path;using-sidebar-versions-clist.png" format="PNG" />
-            </imageobject>
-        </inlinemediaobject>
-    </para>
-    
-    <para>
-        The combined list shows the versions together with the actions/filters applied to them. Here the second version was created by resizing the original, applying the unsharp mask, correcting the white balance and finally adding a frame with the border tool. The child versions are grouped in Derived Versions and Related Versions. Related Versions arise if you modify the original and save the changes with <guilabel>Save As New Version</guilabel>.
-    </para>
-    
-    <para>
-        To learn how to control what is stored as a separate version and which versions are displayed in the Image Area see <link linkend="using-setup-editor-version">Image Versioning Settings</link>.
-    </para>
-
-</sect2>
-
-<!--
-Local Variables:
-mode: sgml
-sgml-minimize-attributes:nil
-sgml-general-insert-case:lower
-sgml-indent-step:0
-sgml-indent-data:nil
-End:
--->
diff --git a/index.rst b/index.rst
index 7ab46a2..88aa4fe 100644
--- a/index.rst
+++ b/index.rst
@@ -141,6 +141,10 @@ The Right Sidebar
 
         :ref:`captions_view`
 
+    .. container:: tile no-descr
+
+        :ref:`versions_view`
+
 .. toctree::
    :maxdepth: 2
    :hidden:
diff --git a/right_sidebar.rst b/right_sidebar.rst
index 2565a87..dbac9b3 100644
--- a/right_sidebar.rst
+++ b/right_sidebar.rst
@@ -27,3 +27,4 @@ Using the digiKam right sidebar
    right_sidebar/colors_view.rst
    right_sidebar/maps_view.rst
    right_sidebar/captions_view.rst
+   right_sidebar/versions_view.rst
diff --git a/attic/digikam/using-sidebar-versions-clist.png b/right_sidebar/images/using-sidebar-versionsclist.png
similarity index 100%
rename from attic/digikam/using-sidebar-versions-clist.png
rename to right_sidebar/images/using-sidebar-versionsclist.png
diff --git a/attic/digikam/using-sidebar-versions-tree.png b/right_sidebar/images/using-sidebar-versionstree.png
similarity index 100%
rename from attic/digikam/using-sidebar-versions-tree.png
rename to right_sidebar/images/using-sidebar-versionstree.png
diff --git a/right_sidebar/versions_view.rst b/right_sidebar/versions_view.rst
new file mode 100644
index 0000000..ba6d02b
--- /dev/null
+++ b/right_sidebar/versions_view.rst
@@ -0,0 +1,28 @@
+.. meta::
+   :description: digiKam Right Sidebar Versions View
+   :keywords: digiKam, documentation, user manual, photo management, open source, free, learn, easy
+
+.. metadata-placeholder
+
+   :authors: - Gilles Caulier <caulier dot gilles at gmail dot com>
+
+   :license: Creative Commons License SA 4.0
+
+.. _versions_view:
+
+Versions View
+=============
+
+.. contents::
+
+The Versions tab shows the history and the saved versions of a photograph. With the three buttons in the top right corner you can choose between a simple list of the saved versions, a tree view and a combined list that shows the versions together with the actions performed with the selected photograph.
+
+.. figure:: images/using-sidebar-versionstree.png
+
+The tree view shows the parent and child versions of the selected image. Here the second and the fifth version derive directly from the original image, the third and forth version are children of the second version.
+
+.. figure:: images/using-sidebar-versionsclist.png
+
+The combined list shows the versions together with the actions/filters applied to them. Here the second version was created by resizing the original, applying the unsharp mask, correcting the white balance and finally adding a frame with the border tool. The child versions are grouped in Derived Versions and Related Versions. Related Versions arise if you modify the original and save the changes with Save As New Version.
+
+To learn how to control what is stored as a separate version and which versions are displayed in the Image Area see :ref:`Image Versioning Settings <using-setup-editor-version>`.


More information about the kde-doc-english mailing list