pdf enhancement

laurent-martin · laurent-martin · commit c2b4814ad64a · 2026-03-21T00:03:26.000+01:00
Signed-off-by: Laurent Martin &lt;laurent.martin.l@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -5,6 +5,8 @@
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5861/badge)](https://bestpractices.coreinfrastructure.org/projects/5861)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
+![Hootput the Owl](docs/mascot.svg)
+
 **`ascli`** is the command-line interface for IBM Aspera products.
 Use it from the terminal or in scripts to:
 
diff --git a/build/doc/pandoc/defaults_pdf.yaml b/build/doc/pandoc/defaults_pdf.yaml
@@ -1,6 +1,8 @@
 # Pandoc options : see https://pandoc.org/MANUAL.html
 to: pdf
 pdf-engine: lualatex
+pdf-engine-opts:
+  - "-shell-escape"
 variables:
   documentclass: report
   mainfont: "IBM Plex Sans"
diff --git a/build/doc/pandoc/pdf_in_header.tex b/build/doc/pandoc/pdf_in_header.tex
@@ -19,6 +19,7 @@
 }
 % https://ctan.org/pkg/graphicx
 \usepackage{graphicx}
+\usepackage{svg}
 % https://ctan.org/pkg/eso-pic
 \usepackage{eso-pic}
 \AddToShipoutPictureBG*{
diff --git a/build/lib/pandoc.rb b/build/lib/pandoc.rb
@@ -60,6 +60,14 @@ def generate_gfx_paths_latex(paths)
   result
 end
 
+def check_add_defaults_file(md, format, additional)
+  add_defaults = Pathname.new(md).dirname / ".#{Pathname.new(md).basename}.#{format}.pandoc.yaml"
+  log.info{"checking defaults: #{add_defaults}"}
+  return unless add_defaults.exist?
+  log.info{"Using default pandoc defaults: #{add_defaults}"}
+  additional << add_defaults
+end
+
 # Generate PDF from Markdown using pandoc templates
 def markdown_to_pdf(md:, pdf:)
   log.info{"Generating: #{pdf}"}
@@ -70,19 +78,25 @@ def markdown_to_pdf(md:, pdf:)
   Dir.chdir(File.dirname(md)) do
     md = File.basename(md)
     custom_defaults_file = extract_pandoc_defaults_file(md)
-    gfx_paths_latex = generate_gfx_paths_latex([PATH_PANDOC_ROOT])
+    gfx_paths_latex = generate_gfx_paths_latex([PATH_PANDOC_ROOT, '.'])
+    defaults = [
+      PATH_PANDOC_ROOT / 'defaults_common.yaml',
+      PATH_PANDOC_ROOT / 'defaults_pdf.yaml',
+      custom_defaults_file
+    ]
+    check_add_defaults_file(md, 'pdf', defaults)
     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'}",
-      "--defaults=#{custom_defaults_file}",
+      *defaults.map{ |f| "--defaults=#{f}"},
       "--output=#{pdf}",
       md
     )
     custom_defaults_file.delete
     gfx_paths_latex.delete
+    # temporary files
+    FileUtils.rm_rf('svg-inkscape')
   end
 end
 
diff --git a/build/lib/paths.rb b/build/lib/paths.rb
@@ -36,7 +36,9 @@ module Paths
   TMPL_CONF_FILE = DOC / 'test_env.conf'
   TSPEC_JSON_SCHEMA = DOC / 'spec.schema.json'
   ASPERA_CONF_XSD = DOC / 'aspera.conf.xsd'
-  UML_PNG = Paths::DOC / 'uml.png'
+  UML_PNG = DOC / 'uml.png'
+  MASCOT_SVG = DOC / 'mascot.svg'
+  MASCOT_PDF = DOC / 'mascot.pdf'
   MD_MANUAL = DOC / 'README.md'
   MD_ERB = DOC / 'README.erb.md'
   TSPEC_YAML_SCHEMA = LIB / 'aspera/transfer/spec.schema.yaml'
diff --git a/docs/.README.md.pdf.pandoc.yaml b/docs/.README.md.pdf.pandoc.yaml
@@ -0,0 +1,2 @@
+include-before-body:
+  - .README.md.pdf.tex
diff --git a/docs/.README.md.pdf.tex b/docs/.README.md.pdf.tex
@@ -0,0 +1,27 @@
+\thispagestyle{empty}
+\vspace*{\fill}
+\begin{center}
+\includesvg[width=8cm,keepaspectratio]{mascot.svg}
+
+\vspace{4cm}
+\large
+\itshape
+"Hey, I'm ascli - your data's personal courier.
+
+I don't do flashy dashboards; I'm happiest in a terminal window.
+
+Hand me a command, and I'll zip your files across the network faster than you thought possible.
+
+Need to automate? I'm script-friendly.
+
+Need to integrate? I've got APIs on speed-dial.
+
+Need to debug? I'll show you what's going on under the hood.
+
+Think of me as Aspera's command-line sidekick: quick, reliable, and a little no-nonsense.
+
+You bring the files; I'll bring the horsepower."
+\normalsize
+\end{center}
+\vspace*{4cm}
+\newpage
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+svg-inkscape
diff --git a/docs/README.erb.md b/docs/README.erb.md
@@ -5,32 +5,15 @@ PANDOC_DEFAULTS_BEGIN
 metadata:
   subtitle: "<%=cmd%> <%=build_version%>"
   author: "<%=gemspec.authors.join(', ')%>"
-variables:
-  include-before:
-    - ''
 PANDOC_DEFAULTS_END
 -->
 
-<!-- NOTE CAUTION WARNING IMPORTANT TIP INFO -->
+<!-- Admonitions: NOTE CAUTION WARNING IMPORTANT TIP INFO -->
 
 <!-- markdownlint-disable MD028 -->
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD060 -->
 
-![Hootput the Owl](<%=link_repo('docs/mascot.svg')%>)
-
-"Hey, I’m <%=tool%> - your data’s personal courier.
-I don’t do flashy dashboards; I’m happiest in a terminal window.
-Hand me a command, and I’ll zip your files across the network faster than you thought possible.
-
-Need to automate? I’m script-friendly.
-
-Need to integrate? I’ve got APIs on speed-dial.
-
-Need to debug? I’ll show you what’s going on under the hood.
-
-Think of me as Aspera’s command-line sidekick: quick, reliable, and a little no-nonsense. You bring the files; I’ll bring the horsepower."
-
 ## Introduction
 
 ### Overview
diff --git a/docs/README.md b/docs/README.md
@@ -5,33 +5,16 @@ PANDOC_DEFAULTS_BEGIN
 metadata:
   subtitle: "ascli 4.26.0.pre"
   author: "Laurent Martin"
-variables:
-  include-before:
-    - ''
 PANDOC_DEFAULTS_END
 -->
 <!-- markdownlint-disable MD033 -->
 
-<!-- NOTE CAUTION WARNING IMPORTANT TIP INFO -->
+<!-- Admonitions: NOTE CAUTION WARNING IMPORTANT TIP INFO -->
 
 <!-- markdownlint-disable MD028 -->
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD060 -->
 
-![Hootput the Owl](mascot.svg)
-
-"Hey, I’m `ascli` - your data’s personal courier.
-I don’t do flashy dashboards; I’m happiest in a terminal window.
-Hand me a command, and I’ll zip your files across the network faster than you thought possible.
-
-Need to automate? I’m script-friendly.
-
-Need to integrate? I’ve got APIs on speed-dial.
-
-Need to debug? I’ll show you what’s going on under the hood.
-
-Think of me as Aspera’s command-line sidekick: quick, reliable, and a little no-nonsense. You bring the files; I’ll bring the horsepower."
-
 ## Introduction
 
 ### Overview
@@ -4823,7 +4806,7 @@ DESCRIPTION
         Use Aspera application to perform operations on command line.
         Documentation and examples: https://rubygems.org/gems/aspera-cli
         execute: ascli conf doc
-        or visit: https://www.rubydoc.info/gems/aspera-cli
+        or visit: https://ibm.biz/ascli-doc
         source repo: https://github.com/IBM/aspera-cli
 
 ENVIRONMENT VARIABLES
@@ -10129,6 +10112,6 @@ ascli config coffee
 
 Ruby gem: [https://rubygems.org/gems/aspera-cli](https://rubygems.org/gems/aspera-cli)
 
-Ruby Doc: [https://www.rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/gems/aspera-cli)
+Ruby Doc: [https://ibm.biz/ascli-doc](https://ibm.biz/ascli-doc)
 
 [Aspera APIs on IBM developer](https://developer.ibm.com/apis/catalog/?search=aspera)
diff --git a/lib/aspera/cli/info.rb b/lib/aspera/cli/info.rb
@@ -7,7 +7,8 @@ module Info
       CMD_NAME = 'ascli'
       # Name of the containing gem, same as in <gem name>.gemspec
       GEM_NAME = 'aspera-cli'
-      DOC_URL  = "https://www.rubydoc.info/gems/#{GEM_NAME}"
+      DOC_URL  = 'https://ibm.biz/ascli-doc'
+      RUBYDOC_URL = "https://www.rubydoc.info/gems/#{GEM_NAME}"
       GEM_URL  = "https://rubygems.org/gems/#{GEM_NAME}"
       SRC_URL  = 'https://github.com/IBM/aspera-cli'
       CONTAINER = 'docker.io/martinlaurent/ascli'
diff --git a/rakelib/doc.rake b/rakelib/doc.rake
@@ -105,6 +105,11 @@ namespace :doc do
     end
   end
 
+  # file Paths::MASCOT_PDF => [Paths::MASCOT_SVG] do
+  #  Aspera::Log.log.info{"Generating: #{Paths::MASCOT_PDF}"}
+  #  run('inkscape', "--export-filename=#{Paths::MASCOT_PDF}", Paths::MASCOT_SVG)
+  # end
+
   desc 'Generate uml'
   task uml: Paths::UML_PNG
 end

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@`
`19`	`19`	`}`
`20`	`20`	`% https://ctan.org/pkg/graphicx`
`21`	`21`	`\usepackage{graphicx}`
	`22`	`+\usepackage{svg}`
`22`	`23`	`% https://ctan.org/pkg/eso-pic`
`23`	`24`	`\usepackage{eso-pic}`
`24`	`25`	`\AddToShipoutPictureBG*{`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+include-before-body:`
	`2`	`+ - .README.md.pdf.tex`