# HG changeset patch
# User Markus Mützel <markus.muetzel@gmx.de>
# Date 1634466531 -7200
# Node ID 33d895260fa4067f6f5e105f295bfd1a83bd474b
# Parent  ba4aebad10d1c40d160e466361ad8826c4893361
publish.m: Support some non-ASCII characters in comments for pdf output.

* scripts/miscellaneous/publish.m: Clarify documentation. Publishing Markup is
  only interpreted in section comments. Remove sentence that suggests that
  commands in the output format might be interpreted in that format.
* scripts/miscellaneous/private/__publish_latex_output__.m: Add substitution
  rules for some multi-byte UTF-8 characters (mostly Latin-based) to LaTeX
  publish template. This fixes a bug where using these characters in comments
  would cause `pdflatex` to fail.

See: https://github.com/gnu-octave/octave/pull/5

diff -r ba4aebad10d1 -r 33d895260fa4 scripts/miscellaneous/private/__publish_latex_output__.m
--- a/scripts/miscellaneous/private/__publish_latex_output__.m	Wed Oct 13 10:36:20 2021 -0700
+++ b/scripts/miscellaneous/private/__publish_latex_output__.m	Sun Oct 17 12:28:51 2021 +0200
@@ -137,6 +137,15 @@
 '\usepackage[T1]{fontenc}',
 '\usepackage{lmodern}');
 
+  # "lstlisting" doesn't support multi-byte UTF-8 characters.
+  # Add substitution rules for some characters (commonly used in languages with
+  # Latin-based script).
+  # Set of substitions taken from:
+  # https://en.wikibooks.org/w/index.php?title=LaTeX/Source_Code_Listings&oldid=3815132#Encoding_issue
+  # FIXME: Any multi-byte UTF-8 character in a non-section comment without a
+  #        substitution rule will still cause an error.  This should be fixed
+  #        more generally, or a way how to work around this limitation should
+  #        be documented.
   listings_option = sprintf ("%s\n",
 "",
 "",
@@ -146,7 +155,26 @@
 'frame=single,',
 'tabsize=2,',
 'showstringspaces=false,',
-'breaklines=true}');
+'breaklines=true,',
+'inputencoding=utf8,',
+'extendedchars=true,',
+'literate=',
+'  {á}{{\''a}}1 {é}{{\''e}}1 {í}{{\''i}}1 {ó}{{\''o}}1 {ú}{{\''u}}1',
+'  {Á}{{\''A}}1 {É}{{\''E}}1 {Í}{{\''I}}1 {Ó}{{\''O}}1 {Ú}{{\''U}}1',
+'  {à}{{\`a}}1 {è}{{\`e}}1 {ì}{{\`i}}1 {ò}{{\`o}}1 {ù}{{\`u}}1',
+'  {À}{{\`A}}1 {È}{{\''E}}1 {Ì}{{\`I}}1 {Ò}{{\`O}}1 {Ù}{{\`U}}1',
+'  {ä}{{\"a}}1 {ë}{{\"e}}1 {ï}{{\"i}}1 {ö}{{\"o}}1 {ü}{{\"u}}1',
+'  {Ä}{{\"A}}1 {Ë}{{\"E}}1 {Ï}{{\"I}}1 {Ö}{{\"O}}1 {Ü}{{\"U}}1',
+'  {â}{{\^a}}1 {ê}{{\^e}}1 {î}{{\^i}}1 {ô}{{\^o}}1 {û}{{\^u}}1',
+'  {Â}{{\^A}}1 {Ê}{{\^E}}1 {Î}{{\^I}}1 {Ô}{{\^O}}1 {Û}{{\^U}}1',
+'  {ã}{{\~a}}1 {ẽ}{{\~e}}1 {ĩ}{{\~i}}1 {õ}{{\~o}}1 {ũ}{{\~u}}1',
+'  {Ã}{{\~A}}1 {Ẽ}{{\~E}}1 {Ĩ}{{\~I}}1 {Õ}{{\~O}}1 {Ũ}{{\~U}}1',
+'  {œ}{{\oe}}1 {Œ}{{\OE}}1 {æ}{{\ae}}1 {Æ}{{\AE}}1 {ß}{{\ss}}1',
+'  {ű}{{\H{u}}}1 {Ű}{{\H{U}}}1 {ő}{{\H{o}}}1 {Ő}{{\H{O}}}1',
+'  {ç}{{\c c}}1 {Ç}{{\c C}}1 {ø}{{\o}}1 {å}{{\r a}}1 {Å}{{\r A}}1',
+'  {€}{{\euro}}1 {£}{{\pounds}}1 {«}{{\guillemotleft}}1',
+'  {»}{{\guillemotright}}1 {ñ}{{\~n}}1 {Ñ}{{\~N}}1 {¿}{{?`}}1 {¡}{{!`}}1',
+'}');
 
   latex_head = sprintf ("%s\n",
 "",
diff -r ba4aebad10d1 -r 33d895260fa4 scripts/miscellaneous/publish.m
--- a/scripts/miscellaneous/publish.m	Wed Oct 13 10:36:20 2021 -0700
+++ b/scripts/miscellaneous/publish.m	Sun Oct 17 12:28:51 2021 +0200
@@ -33,10 +33,12 @@
 ## Generate a report from the Octave script file @var{file} in one of several
 ## output formats.
 ##
-## The generated reports interpret any Publishing Markup in comments, which is
-## explained in detail in the GNU Octave manual.  Assume the following example,
-## using some Publishing Markup, to be the contents of the script file
-## @file{pub_example.m}:
+## The generated reports interpret Publishing Markup in section comments, which
+## is explained in detail in the GNU Octave manual.  Section comments are
+## comment blocks that start with a line with double comment character.
+##
+## Assume the following example, using some Publishing Markup, to be the
+## contents of the script file @file{pub_example.m}:
 ##
 ## @example
 ## @group
@@ -61,12 +63,11 @@
 ##
 ## To publish this script file, type @code{publish ("pub_example.m")}.
 ##
-## With only @var{file} given, a HTML report is generated in a subdirectory
-## @file{html} relative to the current working directory.  The Octave commands
-## are evaluated in a separate context and any figures created while executing
-## the script file are included in the report.  All formatting syntax of
-## @var{file} is treated according to the specified output format and included
-## in the report.
+## When called with one input argument, a HTML report is generated in a
+## subdirectory @file{html} relative to the current working directory.  Any
+## Octave commands in @file{pub_example.m} are evaluated in a separate context
+## and any figures created while executing the script file are included in the
+## report.
 ##
 ## Using @code{publish (@var{file}, @var{output_format})} is equivalent to the
 ## function call using a structure