Improve code snapshot generation for PDF docs (#1353)

CMake: execute `code_snapshot` separately for each file we want to
  scan so we can create timestamps and generate PNG images only if
  the source file (e.g. unicode.dox) was modified.

documentation/src/unicode.dox: remove output folder `generated`, use
  only the filename. CMake sets the current working directory as needed.

util/code_snapshot.cxx: format and improve comments, reset code buffer
  so we can generate multiple images per input file.

2 files changed, 40 insertions, 6 deletions

diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt
index 6c8524ffe..ada291af2 100644
--- a/documentation/CMakeLists.txt
+++ b/documentation/CMakeLists.txt
@@ -202,11 +202,42 @@ if(FLTK_BUILD_PDF_DOCS)
     @ONLY
   )
 
-  # generate fltk.pdf
+  # Generate code snapshots (images with international characters).
+  # Note: File names (even from different folders) must be unique !
+
+  set(image_output_dir "${CMAKE_CURRENT_BINARY_DIR}/generated")
+  set(_deps)
+  set(image_input_sources
+      ${CMAKE_CURRENT_SOURCE_DIR}/src/unicode.dox
+      # ${CMAKE_CURRENT_SOURCE_DIR}/src/cmp.dox
+      # ${FLTK_SOURCE_DIR}/src/Fl.cxx # example source file
+  )
+
+  # Generate one custom command and one timestamp per input file
+  # so dependencies can be used to generate the images only if
+  # the source file was changes.
+  # Variable `_deps` is used to make the final PDF generation
+  # depend on all input files.
+
+  foreach(_infile ${image_input_sources})
+    get_filename_component(_name "${_infile}" NAME)
+    set(_timestamp ${image_output_dir}/${_name}.timestamp)
+    list(APPEND _deps ${_timestamp})
+    # create custom command
+    add_custom_command(
+      OUTPUT  ${_timestamp}
+      COMMAND touch ${_timestamp}
+      COMMAND code_snapshot ${_infile}
+      DEPENDS ${_infile}
+      WORKING_DIRECTORY ${image_output_dir}
+      COMMENT "Generating code snapshots (PNG) from '${_infile}'"
+    )
+  endforeach()
+
+  # Now generate the PDF file (fltk.pdf)
 
   add_custom_command(
     OUTPUT  ${CMAKE_CURRENT_BINARY_DIR}/fltk.pdf
-    COMMAND code_snapshot ${CMAKE_CURRENT_SOURCE_DIR}/src/unicode.dox
     COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/make_header
             ${DOXYGEN_EXECUTABLE}
             ${CMAKE_CURRENT_BINARY_DIR}/fltk-title.tex
@@ -214,8 +245,11 @@ if(FLTK_BUILD_PDF_DOCS)
     COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE}
     COMMAND ${CMAKE_CURRENT_BINARY_DIR}/make_pdf
     COMMAND cp -f latex/refman.pdf fltk.pdf
-    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+            ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}.in
+            ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}
             ${CMAKE_CURRENT_BINARY_DIR}/fltk-title.tex
+            ${_deps} # source files processed to generate PNG's
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
     COMMENT "Generating PDF documentation" VERBATIM
   )
diff --git a/documentation/src/unicode.dox b/documentation/src/unicode.dox
index b640e170e..c11308ca3 100644
--- a/documentation/src/unicode.dox
+++ b/documentation/src/unicode.dox
@@ -22,7 +22,7 @@ are not yet implemented.
 
 International code test for HTML and PDF:
 
-\code_international{"generated/unicode_about.png"}
+\code_international{"unicode_about.png"}
 // This is a test
 // 日本語テストテキスト
 // 中文测试文本
@@ -70,11 +70,11 @@ doesn't break legacy ASCII code.
 Functions to check and analyze UTF-8 text:
 
 fl_utf8test() - Check if a string contains valid UTF-8
-\code
+\code_international{"unicode_hello.png"}
 const char* text = "Hello 世界";
 int result = fl_utf8test(text, strlen(text));
 // Returns: 0=invalid, 1=ASCII, 2=2-byte chars, 3=3-byte chars, 4=4-byte chars
-\endcode
+\endcode_international
 
 fl_utf8len() - Get the length in bytes of a UTF-8 octet
 \code