pandoc tool

Signed-off-by: Laurent Martin <laurent.martin.l@gmail.com>

Author: laurent-martin

build/doc/pandoc/README.md

@@ -22,21 +22,22 @@ clean:
 
 There is a default target for `%.pdf` from `%.md`.
 
-If the source and destination have different basenames or path, then it is possible to do:
+If the source and destination have different base names or path, then it is possible to do:
 
 ```makefile
 $(eval $(call markdown_to_pdf,source.md,target.pdf))
 ```
 
 1. Run `make` to generate the PDF file.
 
-The markdown file can include a section like this with `pandoc` metadata:
+The markdown file can include a section like this with `pandoc` defaults:
 
 ```xml
 <!--
-PANDOC_META_BEGIN
-subtitle: "subtitle here"
-author: "Johnny Beegood"
-PANDOC_META_END
+PANDOC_DEFAULTS_BEGIN
+metadata:
+  subtitle: "subtitle here"
+  author: "Johnny Beegood"
+PANDOC_DEFAULTS_END
 -->
 ```

build/doc/pandoc/pandoc.mak

@@ -1,47 +1,16 @@
 # See README.md for more information
 DIR_PANDOC := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
-DEF_COMMON=$(DIR_PANDOC)defaults_common.yaml
-DEF_PDF=$(DIR_PANDOC)defaults_pdf.yaml
-DEF_HTML=$(DIR_PANDOC)defaults_html.yaml
-PANDOC_DEPS=\
-$(DIR_PANDOC)break_replace.lua \
-$(DEF_COMMON) \
-$(DEF_PDF) \
-$(DEF_HTML) \
-$(DIR_PANDOC)find_admonition.lua \
-$(DIR_PANDOC)gfm_admonition.css \
-$(DIR_PANDOC)gfm_admonition.lua \
-$(DIR_PANDOC)pdf_after_body.tex \
-$(DIR_PANDOC)pdf_in_header.tex \
-$(DIR_PANDOC)pandoc.mak
-TEX_ADD_SUFFIX=.pandoc_add.tex
-META_ADD_SUFFIX=.pandoc_meta.yaml
+DOC_GENERATOR := $(DIR_PANDOC)../../lib/pandoc.rb
+PANDOC_DEPS := $(shell ruby $(DOC_GENERATOR) deps) $(DIR_PANDOC)pandoc.mak $(DOC_GENERATOR)
 
 define markdown_to_pdf
 $(2): $(1) $$(PANDOC_DEPS)
-	-sed -n '/PANDOC_META_BEGIN/,/PANDOC_META_END/p' $$< | grep -v PANDOC_META > $$<$(META_ADD_SUFFIX)
-	echo '\\graphicspath{{$(DIR_PANDOC)}}' > $$<$(TEX_ADD_SUFFIX)
-	set -x &&\
-	if git status --porcelain $$< > /dev/null 2>&1 && test -z "$$$$(git status --porcelain $$<)";then \
-	  ref="-r $$$$(git log -1 --pretty="format:%cd" --date=unix $$<)";fi &&\
-	  pandoc \
-	    --include-in-header=$$<$(TEX_ADD_SUFFIX) \
-		--defaults=$$(DEF_COMMON) \
-		--defaults=$$(DEF_PDF) \
-		--variable=date:"$$$$(/bin/date $$$$ref '+%Y/%m/%d')" \
-	    --metadata-file=$$<$(META_ADD_SUFFIX) \
-		--output=$$@ \
-		$$<
-	rm -f $$<$(META_ADD_SUFFIX) $$<$(TEX_ADD_SUFFIX)
+	$(DOC_GENERATOR) pdf $$< $$@
 endef
 
 define markdown_to_html
 $(2): $(1) $$(PANDOC_DEPS)
-	pandoc \
-		--defaults=$$(DEF_COMMON) \
-		--defaults=$$(DEF_HTML) \
-		--output=$$@ \
-		$$<
+	$(DOC_GENERATOR) html $$< $$@
 endef
 
 $(eval $(call markdown_to_pdf,%.md,%.pdf))

build/lib/doc_helper.rb

@@ -303,6 +303,7 @@ def include_asession
     ['$(PATH_FILE_LIST)', 'file_list.txt'],
     ['$(PATH_VAULT_FILE)', '/secure/vault_file'],
     ['$(path_file_pair_list)', 'file_pair_list.txt'],
+    ['$(remote_host)', 'app.example.com'],
     ['"my_password"', '"my_password_here"'],
     ['$(name) $(PACKAGE_TITLE_BASE)', 'package title'],
     [/^--base=.*/, '--base=test'],

build/lib/pandoc.rb

@@ -1,10 +1,12 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'pathname'
 require_relative 'paths'
 require_relative 'build_tools'
 
 include BuildTools
+include Paths
 
 # Path to pandoc root directory
 PATH_PANDOC_ROOT = ENV.key?('DIR_PANDOC') ? Pathname.new(ENV['DIR_PANDOC']) : Paths::PANDOC
@@ -21,21 +23,21 @@
   'pdf_in_header.tex'
 ].map{ |f| (PATH_PANDOC_ROOT / f).to_s}.freeze
 
-# Extract pandoc metadata from markdown comment
-def extract_metadata_file(md)
-  metadata_file = TMP / 'pandoc_meta.yaml'
+# Extract pandoc defaults from markdown comment
+def extract_pandoc_defaults_file(md)
+  custom_tmp_file = TMP / 'custom_defaults.yaml'
   inside = false
-  File.open(metadata_file, 'w') do |out|
+  File.open(custom_tmp_file, 'w') do |out|
     File.foreach(md.to_s) do |line|
       if !inside
-        inside = true if line.include?('PANDOC_META_BEGIN')
+        inside = true if line.include?('PANDOC_DEFAULTS_BEGIN')
         next
       end
-      break if line.include?('PANDOC_META_END')
+      break if line.include?('PANDOC_DEFAULTS_END')
       out.write(line)
     end
   end
-  metadata_file
+  custom_tmp_file
 end
 
 # Get latest git change date, or else just the file's modification date
@@ -54,7 +56,7 @@ def get_change_date(md)
 def generate_gfx_paths_latex(paths)
   result = TMP / 'pandoc_add.tex'
   # https://latexref.xyz/_005cgraphicspath.html
-  result.write("\\graphicspath{#{paths.map{ |p| "{#{p}}"}.join('')}}\n")
+  result.write("\\usepackage{graphicx}\n\\graphicspath{#{paths.map{ |p| "{#{p}}"}.join('')}}\n")
   result
 end
 
@@ -67,19 +69,19 @@ def markdown_to_pdf(md:, pdf:)
   # Paths in README.md are relative to its location
   Dir.chdir(File.dirname(md)) do
     md = File.basename(md)
-    metadatafile = extract_metadata_file(md)
+    custom_defaults_file = extract_pandoc_defaults_file(md)
     gfx_paths_latex = generate_gfx_paths_latex([PATH_PANDOC_ROOT])
     run(
       'pandoc',
       "--include-in-header=#{gfx_paths_latex}",
+      "--variable=date:#{get_change_date(md)}",
       "--defaults=#{PATH_PANDOC_ROOT / 'defaults_common.yaml'}",
       "--defaults=#{PATH_PANDOC_ROOT / 'defaults_pdf.yaml'}",
-      "--variable=date:#{get_change_date(md)}",
-      "--metadata-file=#{metadatafile}",
+      "--defaults=#{custom_defaults_file}",
       "--output=#{pdf}",
       md
     )
-    metadatafile.delete
+    custom_defaults_file.delete
     gfx_paths_latex.delete
   end
 end
@@ -99,3 +101,78 @@ def markdown_to_html(md:, html:)
     )
   end
 end
+
+# Main execution block when script is run directly
+if __FILE__ == $0
+  # Print usage information
+  def print_usage
+    warn(<<~USAGE)
+      Usage: #{File.basename($0)} <command> [arguments]
+
+      Commands:
+        deps                          List pandoc dependency files
+        pdf <input.md> <output.pdf>   Convert Markdown to PDF
+        html <input.md> <output.html> Convert Markdown to HTML
+
+      Examples:
+        #{File.basename($0)} deps
+        #{File.basename($0)} pdf README.md output.pdf
+        #{File.basename($0)} html README.md output.html
+    USAGE
+  end
+
+  # Validate arguments and execute conversion
+  begin
+    # Check minimum number of arguments
+    if ARGV.empty?
+      print_usage
+      exit(1)
+    end
+
+    command = ARGV[0].downcase
+
+    # Handle 'deps' command
+    if command == 'deps'
+      puts PANDOC_DEPS.join(' ')
+      exit(0)
+    end
+
+    # Handle conversion commands (pdf, html)
+    if ARGV.length != 3
+      warn('Error: Conversion commands require exactly 3 arguments.')
+      print_usage
+      exit(1)
+    end
+
+    input_file = ARGV[1]
+    output_file = ARGV[2]
+
+    # Validate format
+    unless %w[pdf html].include?(command)
+      warn("Error: Invalid command '#{ARGV[0]}'. Must be 'deps', 'pdf', or 'html'.")
+      print_usage
+      exit(1)
+    end
+
+    # Check if input file exists
+    unless File.exist?(input_file)
+      warn("Error: Input file '#{input_file}' not found.")
+      exit(2)
+    end
+
+    # Execute conversion based on format
+    case command
+    when 'pdf'
+      markdown_to_pdf(md: input_file, pdf: output_file)
+    when 'html'
+      markdown_to_html(md: input_file, html: output_file)
+    end
+
+    puts "Successfully converted #{input_file} to #{output_file}"
+    exit(0)
+  rescue => e
+    warn("Error during conversion: #{e.message}")
+    warn(e.backtrace.join("\n")) if ENV['DEBUG']
+    exit(3)
+  end
+end