Merge branch 'topic/vadim/odf' into 'master'

Support of images by ODF backend

See merge request eng/ide/gnatdoc!176

Author: godunko

documentation/project_file.md

@@ -19,6 +19,11 @@ include any project files directly or undirectly used by the root project.
 Note, externally build library project files are excluded from the
 documentation generation unconditionally.
 
+## Image_Dirs
+
+List of directories (relative to directory of the root project file) to lookup
+for images referenced in the documentation.
+
 ## Output_Dir
 
 Allows to specify output directory for the generated documentation.

documentation/users_guide/backends.rst

@@ -46,6 +46,17 @@ Layout of the resources directory
     style documentation is specified)
 
 
+ODF
+===
+
+The ODF backend can be used to generate documentation in OpenDocument Format
+(ODF) format. The generated file can be opened by many office suites
+(Microsoft Word, LibreOffice Writer, etc) to apply different styles and print
+the documentation.
+
+Output can be customized by providing a custom
+*<resources_dir>/template/documentation.fodt* file.
+
 
 RST
 ===

documentation/users_guide/configuration.rst

@@ -69,3 +69,17 @@ and templates can be specified via the string attribute *Resources_Dir* of the
 
 Each backend has own conventions on the layout of the resources directory: see
 the documentation of the particular backend.
+
+
+Images directories
+------------------
+
+
+List of directories to lookup for image files referenced in the documentation
+can be defined with *Image_Dirs* attribute of the root project file::
+
+   package Documentation is
+      for Image_Dirs ("odf") use ("images");
+   end Documentation;
+
+By default paths are resolved relatively to the project file's root directory.

source/backend/odf/gnatdoc-backend-odf.adb

@@ -20,7 +20,9 @@ with VSS.XML.XmlAda_Readers;
 with VSS.XML.Templates.Processors;
 with VSS.XML.Writers.Simple;
 
+with GNATdoc.Backend.ODF_Markup.Image_Utilities;
 with GNATdoc.Entities.Proxies;
+with GNATdoc.Projects;
 with Streams;
 
 package body GNATdoc.Backend.ODF is
@@ -118,6 +120,24 @@ package body GNATdoc.Backend.ODF is
       Output.Close;
    end Generate;
 
+   ----------------
+   -- Initialize --
+   ----------------
+
+   overriding procedure Initialize (Self : in out ODF_Backend) is
+   begin
+      Abstract_Backend (Self).Initialize;
+
+      if Self.Image_Directories.Is_Empty then
+         GNATdoc.Backend.ODF_Markup.Image_Utilities.Set_Image_Directories
+           ([GNATdoc.Projects.Project_File_Directory]);
+
+      else
+         GNATdoc.Backend.ODF_Markup.Image_Utilities.Set_Image_Directories
+           (Self.Image_Directories);
+      end if;
+   end Initialize;
+
    ----------------------------------
    -- Process_Command_Line_Options --
    ----------------------------------

source/backend/odf/gnatdoc-backend-odf.ads

@@ -25,7 +25,7 @@ private
       null;
    end record;
 
-   --  overriding procedure Initialize (Self : in out RST_Backend_Base);
+   overriding procedure Initialize (Self : in out ODF_Backend);
 
    overriding procedure Generate (Self : in out ODF_Backend);
 

source/backend/odf/gnatdoc-backend-odf_markup-image_utilities.adb

@@ -20,9 +20,13 @@ with GNAT.Strings;
 
 with VSS.Strings.Conversions;
 with VSS.Strings.Converters.Decoders;
+with VSS.Strings.Formatters.Strings;
+with VSS.Strings.Templates;
 
 with GNATCOLL.Coders.Base64;
 
+with GNATdoc.Messages;
+
 package body GNATdoc.Backend.ODF_Markup.Image_Utilities is
 
    type Stream_Element_Array_Access is
@@ -32,6 +36,12 @@ package body GNATdoc.Backend.ODF_Markup.Image_Utilities is
      new Ada.Unchecked_Deallocation
            (Ada.Streams.Stream_Element_Array, Stream_Element_Array_Access);
 
+   Image_Directories : GNATdoc.Virtual_File_Vectors.Vector;
+
+   Not_Found_Template : constant
+     VSS.Strings.Templates.Virtual_String_Template :=
+       "image file '{}' is not found";
+
    -----------------
    -- Load_Encode --
    -----------------
@@ -42,18 +52,30 @@ package body GNATdoc.Backend.ODF_Markup.Image_Utilities is
    is
       use type Ada.Streams.Stream_Element_Offset;
 
+      Name    : constant GNATCOLL.VFS.Filesystem_String :=
+        GNATCOLL.VFS.Filesystem_String
+          (VSS.Strings.Conversions.To_UTF_8_String (Destination));
       File    : GNATCOLL.VFS.Virtual_File;
       Binary  : GNAT.Strings.String_Access;
       Encoded : Stream_Element_Array_Access;
       Coder   : GNATCOLL.Coders.Base64.Encoder_Type;
 
    begin
-      File :=
-        GNATCOLL.VFS.Create_From_UTF8
-          (VSS.Strings.Conversions.To_UTF_8_String (Destination));
+      for Directory of Image_Directories loop
+         File :=
+           GNATCOLL.VFS.Create_From_Base
+             (Base_Name => Name,
+              Base_Dir  => Directory.Full_Name.all);
+
+         exit when File.Is_Regular_File;
+      end loop;
 
       if not File.Is_Regular_File then
-         raise Program_Error;
+         GNATdoc.Messages.Report_Warning
+           (Not_Found_Template.Format
+              (VSS.Strings.Formatters.Strings.Image (Destination)));
+
+         return;
       end if;
 
       Binary := File.Read_File;
@@ -86,4 +108,14 @@ package body GNATdoc.Backend.ODF_Markup.Image_Utilities is
       GNAT.Strings.Free (Binary);
    end Load_Encode;
 
+   ---------------------------
+   -- Set_Image_Directories --
+   ---------------------------
+
+   procedure Set_Image_Directories
+     (To : GNATdoc.Virtual_File_Vectors.Vector) is
+   begin
+      Image_Directories := To;
+   end Set_Image_Directories;
+
 end GNATdoc.Backend.ODF_Markup.Image_Utilities;

source/backend/odf/gnatdoc-backend-odf_markup-image_utilities.ads

@@ -23,4 +23,7 @@ package GNATdoc.Backend.ODF_Markup.Image_Utilities is
    --  Loads given file, converts its content into Base64 encoded form and
    --  transforms to `Virtual_String`.
 
+   procedure Set_Image_Directories (To : GNATdoc.Virtual_File_Vectors.Vector);
+   --  Set list of directories to lookup for image files.
+
 end GNATdoc.Backend.ODF_Markup.Image_Utilities;

source/gnatdoc-messages.adb

@@ -151,4 +151,18 @@ package body GNATdoc.Messages is
         Success);
    end Report_Warning;
 
+   --------------------
+   -- Report_Warning --
+   --------------------
+
+   procedure Report_Warning (Text : VSS.Strings.Virtual_String) is
+      Template : constant Virtual_String_Template := "warning: {}";
+      Success  : Boolean := True;
+      Stream   : VSS.Text_Streams.Output_Text_Stream'Class :=
+        VSS.Text_Streams.Standards.Standard_Error;
+
+   begin
+      Stream.Put_Line (Template.Format (Image (Text)), Success);
+   end Report_Warning;
+
 end GNATdoc.Messages;

source/gnatdoc-messages.ads

@@ -40,6 +40,9 @@ package GNATdoc.Messages is
    procedure Report_Warning (Message : GNATdoc.Messages.Message);
    --  Output warning to standard error stream.
 
+   procedure Report_Warning (Text : VSS.Strings.Virtual_String);
+   --  Output warning to standard error stream.
+
    procedure Report_Error
      (Location : GNATdoc.Source_Location;
       Message  : VSS.Strings.Virtual_String);

source/gnatdoc/gnatdoc-projects.adb

@@ -520,6 +520,15 @@ package body GNATdoc.Projects is
       end loop;
    end Process_Compilation_Units;
 
+   ----------------------------
+   -- Project_File_Directory --
+   ----------------------------
+
+   function Project_File_Directory return GNATCOLL.VFS.Virtual_File is
+   begin
+      return Project_Tree.Root_Project.Dir_Name.Virtual_File;
+   end Project_File_Directory;
+
    -------------------------
    -- Register_Attributes --
    -------------------------