indoctrinatr-tools 0.11.0 → 0.12.0

data/lib/indoctrinatr/templates/documentation/indoctrinatr-technical-documentation-content.tex.erb

@@ -22,15 +22,20 @@
 
 <% end %>
 
-\chapter{Variables}
-		
-\begin{tabu}{ l l X l X }
-	\textbf{Variable} & \textbf{Presentation} & \textbf{Default Value} & \textbf{Required} & \textbf{Description} \\
-	<% @attributes.each do |attribute| %>
-		\texttt{<%= attribute['name'].to_latex -%>}
-		& <%= attribute['presentation'].to_latex -%>
-		& <%= attribute['default_value'].to_latex -%>
-		& <%= 'true' if attribute['required'] == 'true' -%> <%# empty if false or not set. Wish by Søren for better readability-%>
-		& <%= attribute['description'].to_latex -%>\\
-	<% end %>
-\end{tabu}
+\begin{landscape}
+  \chapter{Variables}
+
+  \begin{longtabu}{ l l X l X }
+    \tabletoprule
+    \textbf{Variable} & \textbf{Presentation} & \textbf{Default Value} & \textbf{Required} & \textbf{Description} \\
+    \tabletoprule
+    \endhead
+    <% @attributes.each do |attribute| %>
+      \texttt{<%= attribute['name'].to_latex -%>}
+      & <%= attribute['presentation'].to_latex if attribute['presentation'] -%>
+      & <%= attribute['default_value'].to_latex -%>
+      & <%= 'true' if attribute['required'] == 'true' -%> <%# empty if false or not set. Wish by Søren for better readability-%>
+      & <%= attribute['description'].to_latex if attribute['description'] -%>\\ <%# if condition to ignore errors on empty description field -%>
+    <% end %>
+  \end{longtabu}
+\end{landscape}

data/lib/indoctrinatr/templates/documentation/indoctrinatr-technical-documentation.tex.erb

@@ -9,7 +9,11 @@
 
 % use dkd-letter style to apply design styles
 \usepackage{indoctrinatr-technical-documentation}
+% use custom image macros to show image placeholders
+\usepackage{dkd-image-tools}
 
+% use "pdflscape" package to be able to have several landscape pages in the document
+\usepackage{pdflscape}
 
 %define labels to use in this document
 \newcommand{\dkd}{\emph{dkd}}
@@ -72,6 +76,10 @@
 	% include the prerendered template
 	% pages=- selects all pages
 	\includepdf[pages=-]{<%= @default_values_pdf_path -%>} % template_with_default_values.pdf "#{@template_name}_with_default_values.pdf"
+	<% if @pdf_with_field_names_path %>
+		\chapter{Templated filled with field names}
+		\includepdf[pages=-]{<%= @pdf_with_field_names_path -%>}
+	<% end %>
 	% restore wallpaper
 	\ULCornerWallPaper{1}{indoctrinatr_letterpaper.pdf}
 

data/lib/indoctrinatr/templates/template.tex.erb

@@ -2,7 +2,14 @@
 \documentclass{article}
 
 \begin{document}
-		 \section{Hello <%= variable1 -%>}
-		 
-		 The <%= variable1 -%> is <%= variable2 -%>!
+	\section{Hello <%= variable1 -%>}
+	 
+	The <%= variable1 -%> is <%= variable2 -%>!
+ 
+	Today is \textbf{<%= date -%>}.
+	
+	% This is is the raw, unescaped input of \texttt{variable1}:
+	\begin{verbatim}
+		<%= raw_variable1 -%>
+	\end{verbatim}
 \end{document}

data/lib/indoctrinatr/tools/configuration_extractor.rb

@@ -11,7 +11,7 @@ module Indoctrinatr
         @template_pack_name = template_pack_name
       end
 
-      def call # rubocop:disable Metrics/AbcSize
+      def call
         config_file = YAML.load_file config_file_path
         configuration = TemplatePackConfiguration.new
         configuration.template_asset_path = assets_path.to_s

data/lib/indoctrinatr/tools/content_for_tex_files.rb

@@ -0,0 +1,36 @@
+require 'redcloth'
+
+module Indoctrinatr
+  module Tools
+    class ContentForTexFiles
+      # a class that DefaultValues, TemplateDocumentationContent, and field_names_as_variables should inherit from
+      # or to be precise: When we want use variables in an indoctrinatr tex.erb file, we should use this class
+      def initialize configuration
+        @_configuration = configuration
+        _build_from_configuration
+      end
+
+      def textile2latex textile
+        RedCloth.new(textile).to_latex
+      end
+
+      def retrieve_binding
+        binding
+      end
+
+      def customized_output_file_name
+        @_customized_output_file_name ||= eval('"' + @_output_file_name + '"') # rubocop:disable Lint/Eval
+      end
+
+      def template_asset_path
+        @_template_asset_path
+      end
+
+      def _build_from_configuration
+        @_template_asset_path = @_configuration.template_asset_path
+        @_output_file_name = @_configuration.output_file_name # does this fit here?
+        @_default_file_name = @_configuration.default_file_name # does this fit here?
+      end
+    end
+  end
+end

data/lib/indoctrinatr/tools/default_values.rb

@@ -1,29 +1,8 @@
-require 'redcloth'
+require 'indoctrinatr/tools/content_for_tex_files'
 
 module Indoctrinatr
   module Tools
-    class DefaultValues
-      def initialize configuration
-        @_configuration = configuration
-        _build_from_configuration
-      end
-
-      def textile2latex textile
-        RedCloth.new(textile).to_latex
-      end
-
-      def retrieve_binding
-        binding
-      end
-
-      def customized_output_file_name
-        @_customized_output_file_name ||= eval('"' + @_output_file_name + '"') # rubocop:disable Lint/Eval
-      end
-
-      def template_asset_path
-        @_template_asset_path
-      end
-
+    class DefaultValues < ContentForTexFiles
       def output_file_name
         @_output_file_name
       end
@@ -32,11 +11,7 @@ module Indoctrinatr
         @_default_file_name
       end
 
-      def _build_from_configuration # rubocop:disable Metrics/AbcSize
-        @_template_asset_path = @_configuration.template_asset_path
-        @_output_file_name = @_configuration.output_file_name
-        @_default_file_name = @_configuration.default_file_name
-
+      def _use_default_values # rubocop:disable Metrics/AbcSize
         @_configuration.attributes_as_hashes_in_array.each do |attribute_hash|
           instance_variable_set("@_#{attribute_hash['name']}", attribute_hash['default_value'])
 

data/lib/indoctrinatr/tools/field_name_values.rb

@@ -0,0 +1,57 @@
+require 'indoctrinatr/tools/content_for_tex_files'
+
+module Indoctrinatr
+  module Tools
+    # This class defines the content for a document that has the field names as content.
+    class FieldNameValues < ContentForTexFiles
+      # TODO: extensive list of possibilities
+      PICTURE_FILE_ENDINGS = %w(.png .jpeg .jpg .bmp .gif .pdf).freeze
+      def _field_names_as_values # rubocop:disable Metrics/AbcSize
+        @_configuration.attributes_as_hashes_in_array.each do |attribute_hash|
+          # Usage of \textless to avoid issues with the < > characters.
+          # Usage of * character because it does not produce any issues when it's used in arguments of LaTeX commands.
+          # Initially the intention was to use texttt, but that had this problem.
+          instance_variable_set("@_#{attribute_hash['name']}",
+                                "\\textless***#{attribute_hash['name'].to_latex}***\\textgreater")
+
+          define_singleton_method "raw_#{attribute_hash['name']}".to_sym do
+            "raw\\_#{instance_variable_get("@_#{attribute_hash['name']}")}"
+          end
+
+          define_singleton_method attribute_hash['name'].to_sym do
+            # No usage of to_latex because we escaped variable name already and want no escaping for the other stuff
+            instance_variable_get("@_#{attribute_hash['name']}")
+          end
+        end
+        # This overwrites the instance attributes and methods again
+        overwrite_picture_file_names_output @_configuration.attributes_as_hashes_in_array
+      end
+
+      # The LaTeX compilation would fail if the \includegraphics tries to include a file that does not exist.
+      # Because of that it makes sense to simply use the default values again if user sets file names.
+      def overwrite_picture_file_names_output attributes_as_hashes # rubocop:disable Metrics/AbcSize
+        attributes_as_hashes.each do |attribute_hash|
+          # search for typical picture file endings
+          next unless detect_picture_file_names attribute_hash['default_value']
+          instance_variable_set("@_#{attribute_hash['name']}", attribute_hash['default_value'])
+
+          define_singleton_method "raw_#{attribute_hash['name']}".to_sym do
+            "raw\\_#{instance_variable_get("@_#{attribute_hash['name']}")}"
+          end
+
+          define_singleton_method attribute_hash['name'].to_sym do
+            instance_variable_get("@_#{attribute_hash['name']}").to_latex
+          end
+        end
+      end
+
+      # Indoctrinatr has no picture data type. This means that the only way to check for pictures is to check for
+      # file endings. If an user has obscure file type the possibility list would have to get updated.
+      def detect_picture_file_names string_to_check
+        PICTURE_FILE_ENDINGS.any? do |picture_file_ending|
+          string_to_check.downcase.include? picture_file_ending # http://stackoverflow.com/a/3686568
+        end
+      end
+    end
+  end
+end

data/lib/indoctrinatr/tools/pdf_generator.rb

@@ -0,0 +1,36 @@
+# Unify the command usage for all pdf creation features
+module Indoctrinatr
+  module Tools
+    module PdfGenerator
+      # Compiles a PDF from a tex file with XeLaTeX
+      # @param tex_file a Pathname that points to the tex file
+      # @return false if error, nil if system command unknown
+      def make_pdf tex_file, output_dir = nil, cleanup = true
+        args = ['-xelatex',
+                '-shell-escape',
+                '-interaction=batchmode', # more silent output
+                "-output-directory=#{output_dir}", # without this xelatex tries to use the current working directory
+                tex_file.to_s]
+        if output_dir.nil?
+          args.delete_at 3 # Remove argument if no output dir is wished for. This probably could be done better.
+        end
+        latexmk_successful = system('latexmk', *args) # latexmk instead of running 2.times
+        latex_cleanup output_dir if latexmk_successful == true && cleanup
+        latexmk_successful
+      end
+
+      # Cleans up LaTeX helper files in a specific directory
+      # @param working_directory a Pathname that points the directory that should get cleaned up
+      # @return false if error, nil if system command unknown
+      def latex_cleanup working_directory
+        # latexmk -c apparently cannot cleanup a specified subdirectory. So we have to change the working directory,
+        # run the cleanup command in it and then change back to the directory that we were in. http://tex.stackexchange.com/q/301366/17834
+        current_dir = Dir.getwd
+        Dir.chdir working_directory.to_s if working_directory
+        latexmk_successful = system 'latexmk -c'
+        Dir.chdir current_dir # should be the same as ../../.. # Dir.chdir '../../..'
+        latexmk_successful
+      end
+    end
+  end
+end

data/lib/indoctrinatr/tools/template_documentation_content.rb

@@ -1,3 +1,4 @@
+require 'indoctrinatr/tools/content_for_tex_files'
 require 'indoctrinatr/tools/template_pack_configuration'
 require 'indoctrinatr/tools/directory_helpers'
 require 'indoctrinatr/tools/template_documentation_source_file'
@@ -5,12 +6,14 @@ require 'indoctrinatr/tools/default_values'
 
 module Indoctrinatr
   module Tools
-    class TemplateDocumentationContent
+    class TemplateDocumentationContent < ContentForTexFiles
       include DirectoryHelpers
       include TemplatePackHelpers
 
       attr_accessor :template_pack_name, :list_of_files
 
+      # Overwrite the initialize method because the content is built up much more complex than for the other
+      # ContentForTexFile children.
       def initialize template_pack_name, configuration
         @configuration = configuration
         @template_pack_name = template_pack_name
@@ -18,33 +21,40 @@ module Indoctrinatr
         @attributes = configuration.attributes_as_hashes_in_array # we need: name, presentation, default_value, description
         @template_name = configuration.template_name
         @files = read_template_files_content
-        @default_values_pdf_path = pdf_with_default_values_file_path
-        # should have been generated automatically, error if something went wrong with it:
-        fail IOError, "template with default values does not exist in current directory. Run indoctrinatr pdf #{template_pack_name}" unless File.exist? @default_values_pdf_path
-      end
-
-      def retrieve_binding
-        binding
+        @default_values_pdf_path = default_values_example
+        @pdf_with_field_names_path = fieldname_values_example
       end
 
       private
 
       def read_template_files_content
         filenames = list_files_of_type template_pack_name
+        filenames.reject! { |f| f.include?(pack_documentation_examples_dir_path.relative_path_from(Pathname.new(Dir.pwd)).to_s) }
         filenames.inject [] do |files, filename|
           files.push TemplateDocumentationSourceFile.new filename
         end
       end
 
-      def pdf_with_default_values_file_path
-        # TODO: this would make more sense in one of the Helpers modules, but we don't want to create a new dependency there. Move this when file path shenanigans are generally revised.
-        # get file path for template with default values:
-        default_values = DefaultValues.new @configuration
-        # if there is a change in where the pdf command (compiler class) saves it's output, this logic needs to be updated
-        if default_values.customized_output_file_name == default_values.default_file_name
-          Pathname.new(Dir.pwd).join default_values.customized_output_file_name
+      def default_values_example
+        default_values_compiler = TemplatePackDefaultValuesCompiler.new(template_pack_name)
+        unless default_values_compiler.pdf_exists?
+          TemplatePackDefaultValuesParser.new(template_pack_name).call
+          default_values_compiler.call
+        end
+        pdf_with_default_values_file_path @configuration
+      end
+
+      def fieldname_values_example
+        fieldnames_creator = TemplatePackFieldnamesCreator.new(template_pack_name)
+        # This gives user the option to customize the FieldNameValues Example that is appended in the documentation
+        return pdf_with_fieldname_values_file_path if fieldnames_creator.pdf_exists?
+
+        if fieldnames_creator.call
+          puts 'INFO: Example with field names has been automatically generated for the documentation' # More user information and for testing
+          pdf_with_fieldname_values_file_path
         else
-          Pathname.new(Dir.pwd).join default_values.output_file_name
+          puts 'ERROR: Example with field names could not be created and is not included in documentation'
+          nil
         end
       end
     end

data/lib/indoctrinatr/tools/template_documentation_helpers.rb

@@ -17,6 +17,10 @@ module Indoctrinatr
         documentation_files_path.join 'indoctrinatr-technical-documentation.sty'
       end
 
+      def source_image_tools_package_file_path
+        documentation_files_path.join 'dkd-image-tools.sty'
+      end
+
       def source_letterpaper_file_path
         documentation_files_path.join 'indoctrinatr_letterpaper.pdf'
       end
@@ -29,6 +33,10 @@ module Indoctrinatr
         documentation_compile_dir_path_name.join 'indoctrinatr-technical-documentation.sty'
       end
 
+      def image_tools_package_destination_path
+        documentation_compile_dir_path_name.join 'dkd-image-tools.sty'
+      end
+
       def letterpaper_file_destination_path
         documentation_compile_dir_path_name.join 'indoctrinatr_letterpaper.pdf'
       end
@@ -49,6 +57,11 @@ module Indoctrinatr
         documentation_compile_dir_path_name.join 'indoctrinatr-technical-documentation.log'
       end
 
+      # Accessor method to the attribute for classes that include this module
+      def documentation_temp_dir
+        documentation_compile_dir_path_name
+      end
+
       private
 
       def documentation_files_path

data/lib/indoctrinatr/tools/template_documentation_source_file.rb

@@ -12,18 +12,18 @@ module Indoctrinatr
       private
 
       def set_programming_language
-        case File.extname(@name)
-        when '.tex'
-          language = 'TeX'
-        when '.sty'
-          language = 'TeX'
-        when '.erb' # .erb files are just supposed to be tex.erb files. TODO: more correct
-          language = 'TeX'
-        when '.rb'
-          language = 'Ruby'
-        else # probably YAML
-          language = 'unspecified'
-        end
+        language =  case File.extname(@name)
+                    when '.tex'
+                      'TeX'
+                    when '.sty'
+                      'TeX'
+                    when '.erb' # .erb files are just supposed to be tex.erb files. TODO: more correct
+                      'TeX'
+                    when '.rb'
+                      'Ruby'
+                    else # probably YAML
+                      'unspecified'
+                    end
         language
       end
     end

data/lib/indoctrinatr/tools/template_pack_configuration.rb

@@ -1,6 +1,6 @@
 module Indoctrinatr
   module Tools
-    class TemplatePackConfiguration
+    class TemplatePackConfiguration # wrapper class for config. See ConfigurationExtractor for details
       attr_accessor :template_asset_path, :default_file_name, :template_name, :textual_description, :output_file_name, :attributes_as_hashes_in_array
     end
   end

data/lib/indoctrinatr/tools/template_pack_default_values_compiler.rb

@@ -1,15 +1,18 @@
 require 'indoctrinatr/tools/configuration_extractor'
+require 'indoctrinatr/tools/pdf_generator'
 require 'fileutils'
 
 module Indoctrinatr
   module Tools
     class TemplatePackDefaultValuesCompiler
       include TemplatePackHelpers
+      include PdfGenerator
 
       attr_accessor :template_pack_name
 
-      def initialize template_pack_name
+      def initialize template_pack_name, keep_aux_files = false
         @template_pack_name = template_pack_name
+        @keep_aux_files = keep_aux_files
       end
 
       def call
@@ -18,15 +21,20 @@ module Indoctrinatr
         rename_if_necessary
       end
 
+      def pdf_exists?
+        check_for_folder
+        file_path = pdf_with_default_values_file_path ConfigurationExtractor.new(template_pack_name).call
+        File.exist? file_path
+      end
+
       private
 
       def compile_tex_file
-        args = ['-shell-escape', '-interaction', 'batchmode', tex_with_default_values_file_path.to_s]
-        2.times { system('xelatex', *args) } # run two times for proper table-of-contents and page count handling. TODO: use latexmk
+        make_pdf tex_with_default_values_file_path, pack_documentation_examples_dir_path, !@keep_aux_files
       end
 
       def rename_if_necessary
-        configuration = ConfigurationExtractor.new(template_pack_name).call
+        configuration = ConfigurationExtractor.new(template_pack_name).call # TODO: avoid repeated calling of the ConfigurationExtrator
         @default_values = DefaultValues.new configuration
         return if @default_values.customized_output_file_name == @default_values.default_file_name