Merge branch 'mku/update_user_manual' into 'main'

Addding content for gnatformat user manual

See merge request eng/ide/gnatformat!41

user_manual/user-guide/configuration.rst

@@ -5,8 +5,67 @@ Configuring |GNATformat|
 
 |GNATformat| provides few configurable options that can be provided:
 
-
 * as command line arguments,
 * as project attributes defined at the :file:`.gpr` level.
 
-TO BE CONTINUED!
+
+The command line arguments
+--------------------------
+
+The formatting of your sources can be customized by the following options:
+
+* ``--width`` to be used if the maximum line length in your sources needs to be specified. 
+  If not defined, the default value is set to ``79``.
+* ``--indentation`` is an option allowing to specify the line's indentation size if needed.
+  By default its value is set to ``3``.
+* ``--indentation-kind`` is an option that can be used to specify the indentation kind.
+  The possible values are ``tabs`` or ``spaces``. By default, this value is set to ``spaces``.
+* ``--indentation-continuation`` is an option allowing to specify the continuation line
+  indentation size in case of your source code line should break relatively to the previous line.
+  By default this value is set to ``indentation - 1``.
+* ``--end-of-line`` is an option allowing to choose the end of line sequence in your file
+  (i.e., ``lf`` or ``crlf``). By default, this value is set to ``lf``.
+* ``--charset`` is an option allowing to specify the charset to use for the sources decoding.
+
+The tool allows as well the usage of a custom unparsing configuration file. This file can be
+specified instead of the default one using the ``--unparsing-configuration`` switch taking as
+argument the custom configuration file name. However, for the moment this is only an internal
+switch and its usage is limited for development proposes.
+
+
+The project file attributes
+---------------------------
+
+The formatting of your sources can be customized through the (:file:`.gpr`) project file by defining
+a specific package called ``package Format``.
+In this package all the attributes corresponding to the command line arguments can be added. There is
+a one to one correspondence between the command line arguments and (:file:`.gpr`) project file attributes.
+The attribute has the same functionality as its associated command line argument and can be customized
+in order to comply with a specific source code formatting use case. 
+
+The lines below shows the implementation of the ``Format`` package as part of project file (:file:`.gpr`)::
+  
+  package Format is
+
+    for Indentation ("Ada") use "3"; -- this is the default
+
+    for Indentation ("some_source.ads") use "4";
+
+    for Indentation_Kind ("Ada") use "spaces"; -- this is the default
+
+    for Indentation_Kind ("some_source.ads") use "tabs";
+
+    for Width ("Ada") use "79"; -- this is the default
+
+    for Width ("some_source.ads") use "99";
+
+    for End_Of_Line ("Ada") use "lf"; -- this is the default
+
+    for End_Of_Line ("some_source.ads") use "crlf";
+
+    for Charset ("Ada") use "iso-8869-1"; -- this is the default
+
+    for Charset ("some_source.ads") use "utf-8";
+
+  end Format;
+

user_manual/user-guide/usage.rst

@@ -49,14 +49,36 @@ The specific options allowing to customize the formatting of your sources are:
   In the absence of this, the default value is ``indentation - 1``.
 * ``--end-of-line``: allows you to choose the end of line sequence (i.e., ``lf`` or ``crlf``).
   In the absence of this, the default value is ``lf``.
+* ``--charset``: allows you to specify the charset to use for source decoding.
 
 As a libray
 -----------
 
-The formatting functionality is also available as via a library.
+The formatting functionality is also available via a library.
+
+In order to use it as a libray, the API is located in the (:file:`gnatformat-formattng.ads`)
+and the entry point is the function ``Gnatformat.Formatting.Format`` having the following interface::
+  
+  function Format
+     (Unit           : Libadalang.Analysis.Analysis_Unit;
+      Format_Options : Gnatformat.Configuration.Format_Options_Type;
+      Configuration  :
+        Langkit_Support.Generic_API.Unparsing.Unparsing_Configuration :=
+          Gnatformat.Configuration.Default_Unparsing_Configuration)
+      return Ada.Strings.Unbounded.Unbounded_String;
+   --  Formats the given Unit using the provided Format_Options and
+   --  Configuration.
+
+where:
+* the ``Unit`` is a Libadalang analysis unit node correspondin to the file to be formatted
+* the ``Format_Options`` are formatting the options that are specified through the (:file:`.gpr`)
+  project file
+* the ``Configuration`` uses a predefined configuration, i.e. the `Default_Unparsing_Configuration`,
+  that implements the formatting rules according to the coding style described in the |GNAT-Style|
+  guide.
+
+This entry point can be used in order to integrate with other tools.   
+
+On our side, the ``gnatformat`` library is included in the |ALS| and can therefore be used through
+IDEs like |GNATStudio| and |VSCode|. 
 
-This ``gnatformat`` library is included in the |ALS| and can therefore be used through IDEs
-like |GNATStudio| and |VSCode|. 
-
-
-TO BE COMPLETED!!!