[accessibility/kontrast] doc: Adding documentation

[Vlad Rakhmanin]

Git commit 565438492eafc358cd84cf69f789e23dfb5a424b by Vlad Rakhmanin.
Committed on 09/09/2022 at 07:39.
Pushed by carlschwan into branch 'master'.

Adding documentation
Created documentation for the application based on the docbooks template.

A  +187  -0    doc/index.docbook
A  +-    --    doc/main.png

https://invent.kde.org/accessibility/kontrast/commit/565438492eafc358cd84cf69f789e23dfb5a424b

diff --git a/doc/index.docbook b/doc/index.docbook
new file mode 100644
index 0000000..1a86ea7
--- /dev/null
+++ b/doc/index.docbook
@@ -0,0 +1,187 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
+  <!ENTITY kmyapplication "<application>Kontrast</application>">
+  <!ENTITY i18n-translatable-entity "<application>Translatable Entity</application>">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE">
+]>
+
+<book id="kmyapplication" lang="&language;">
+
+<!-- This header contains all of the meta-information for the document such
+as Authors, publish date, the abstract, and Keywords -->
+
+<bookinfo>
+<title>The &kmyapplication; Handbook</title>
+
+<authorgroup>
+<author>
+<personname>
+<firstname>Carl</firstname>
+<surname>Schwan</surname>
+</personname>
+<email>carl at carlschwan.eu</email>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2022</year>
+<holder>Carl Schwan</holder>
+</copyright>
+
+<date>2022-09-08</date>
+
+<releaseinfo>Version 20.12.0</releaseinfo>
+
+<abstract>
+<para>
+&kmyapplication; is a color contrast checker that allows users to verify if their color combinations are accessible for people with color vision deficiencies.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Accessibility</keyword>
+<keyword>Kontrast</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+&kmyapplication; allows the user to check the contrast ratio between colors and determine if the result is suitable for people with color vision deficiencies. Users may select colors in a variety of ways, for example, by inputting the hex values manually, or by using the color picker tool to select any color value on their screen.
+</para>
+
+<para>
+The contrast ratio check by this application is related to the difference in color between two objects that allows them to be distinguished. A contrast value of 21 indicates a perfect contrast (usually black on white) and a value of 0 indicates that the two colors are the same. The colors are checked against Web Content Accessibility Guidelines (<quote>WCAG</quote>). 
+</para>
+
+</chapter>
+
+
+<chapter id="using-kapp">
+<title>Using &kmyapplication;</title>
+
+
+<para>
+<screenshot>
+<screeninfo>Here's a screenshot of &kmyapplication;</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="main.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot of &kmyapplication;</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+After opening the application, you will be presented with a screen similar to the one above - this is the main screen of &kmyapplication; and contains most of its features. A randomly selected text color, background color and their contrast ratio will be displayed as an example.  
+</para>
+
+<sect1 id="kapp-color-select">
+<title>Selecting Text and Background Colors</title>
+<para>
+There are five main ways in which colors can be selected for comparison. These are outlined below.
+</para>
+
+<sect2 id="hex-values">
+<title>Input Hex Values</title>
+</sect2>
+<para>If you know the hex values of the colors that you would like to check, then you can input them directly. To do so, click on the hex value of the sample color currently on the screen and type in the desired value.</para>
+
+<sect2 id="color-picker">
+<title>Color Picker</title>
+</sect2>
+<para>If there is a color that you currently have on the screen - for example, from a sample image - then you can use the color picker tool to input this color directly into the application. To do so, click the color picker icon to the right of the hex value of the currently selected color, and click the color anywhere on the screen that you would like to sample. The color will then be selected in the application.</para>
+
+<sect2 id="hue">
+<title>Hue, Saturation and Lightness</title>
+</sect2>
+<para>If you would like to tweak your current selection to see if certain changes have an effect on the contrast, then you can do so by using the hue, saturation and lightness sliders. These are located underneath the hex value of the current selection. The color selection will automatically update as you make changes to these sliders.</para>
+
+<sect2 id="invert">
+<title>Invert</title>
+</sect2>
+<para>The <guimenuitem>Invert</guimenuitem> button will swap the two currently selected colors, setting the background color as the text color and vice versa.</para>
+
+<sect2 id="randomize">
+<title>Randomize</title>
+</sect2>
+<para>The <guimenuitem>Randomize</guimenuitem> button will assign random colors to both the background and the text colors.</para>
+</sect1>
+
+<sect1 id="result">
+<title>Contrast Result</title>
+The contrast ratio resulting from your selection will be shown on the top of the screen, together with a short note explaining how well this contrast is suited to text of varying sizes. This text will be updated automatically as changes are made to the color values. 
+</sect1>
+
+<sect1 id="favorite">
+<title>Favorites</title>
+&kmyapplication; allows the user to save favourite color combinations for future reference. To do so, press the <guimenuitem>Mark as favourite</guimenuitem> located at the bottom of the screen. These color combinations can be accessed again through the <guimenuitem>Favorite Colors</guimenuitem> menu item, as more particularly described in the next chapter.
+</sect1>
+</chapter>
+
+<chapter id="menu">
+<title>Menu Options</title>
+
+<para>
+This chapter describes all application features accessible after clicking the <guimenu>Menu</guimenu> icon in the top left corner. 
+</para>
+
+<sect2 id="contrast-checker">
+<title>Contrast Checker</title>
+<para>
+This is the default screen of the application, allowing the user to select colors and view their contrast ratio. The functionality is described in the previous chapter. 
+</para>
+</sect2>
+
+<sect2 id="fave-colors">
+<title>Favorite Colors</title>
+<para>
+This screen will contain all color combinations saved as "favorite" in the <guimenuitem>Contrast Checker</guimenuitem> screen. Color combinations may be deleted by pressing the <guimenuitem>Remove</guimenuitem> button.
+</para>
+</sect2>
+
+<sect2 id="help">
+<title>Help</title>
+<para>
+This screen contains a brief summary of the theory behind this application, with an explanation of how contrast works and how best to interpret the contrast ratio in line with the WCAG standard.
+</para>
+</sect2>
+
+<sect2 id="about">
+<title>About</title>
+<para>
+This screen contains some general information relating to the application, such as the authors and the libraries used. There is also a button that allows users to submit any bug that they may encounter to the developers.
+</para>
+</sect2>
+
+</chapter>
+
+<chapter id="credits">
+
+<title>Credits and License</title>
+
+<para>
+&kmyapplication;
+</para>
+<para>
+Program copyright 2020-2022 Carl Schwan <email>carl at carlschwan.eu</email>
+</para>
+
+<para>
+Documentation Copyright © 2022 Vlad Rakhmanin <email>vladimir.rakhmanin at ucdconnect.ie</email>
+</para>
+
+&underGPL;        	 <!-- GPL License -->
+
+</chapter>
+
+&documentation.index;
+</book>
diff --git a/doc/main.png b/doc/main.png
new file mode 100644
index 0000000..12267f2
Binary files /dev/null and b/doc/main.png differ