* Bug 6911 fixed: help_from_sci dit not support ω in heading comments 42/19442/4
Samuel GOUGEON [Mon, 2 Oct 2017 22:17:18 +0000 (00:17 +0200)]
  http://bugzilla.scilab.org/6911

  In addition,
  * "&" out of HTML entities were not converted into & in the short
    description (and made xmlto#() failing).
  * The indentation of the <variablelist> entries is improved.

Change-Id: I363eaedf82ab5c2b75b8f8ca82dd67b9b43590fc

scilab/CHANGES.md
scilab/modules/helptools/help/en_US/help_from_sci.xml
scilab/modules/helptools/help/pt_BR/help_from_sci.xml
scilab/modules/helptools/macros/help_from_sci.sci
scilab/modules/helptools/tests/nonreg_tests/bug_6911.tst [new file with mode: 0644]
scilab/modules/helptools/tests/nonreg_tests/bug_6911_entities_in_sci_help.sci [new file with mode: 0644]

index b414d5b..ec51b58 100644 (file)
@@ -375,6 +375,7 @@ the [development mailing list](dev@lists.scilab.org) for a particular toolbox.
 * [#6607](http://bugzilla.scilab.org/show_bug.cgi?id=6607): `clear S; S(1:2,1:3).a = 1` yielded an error.
 * [#6608](http://bugzilla.scilab.org/show_bug.cgi?id=6608): Field and data insertion in an array of structures might fail.
 * [#6813](http://bugzilla.scilab.org/show_bug.cgi?id=6813): `makecell` used to create a N>2-D hyperarray yielded an error.
+* [#6911](http://bugzilla.scilab.org/show_bug.cgi?id=6911): `help_from_sci` did not accept numerical HTML entities like `&#969;` in heading comments.
 * [#7652](http://bugzilla.scilab.org/show_bug.cgi?id=7652): Inserting `list("")` in a cells array could be erroneous.
 * [#8297](http://bugzilla.scilab.org/show_bug.cgi?id=8297): `cat` slowness was exponential, crippling, and made it useless.
 * [#8669](http://bugzilla.scilab.org/show_bug.cgi?id=8669): After `A=rand(3,3)`, some legal insertions in `A(*,*,:)` failed. Non regression tests added.
index 6b5058e..743a57c 100644 (file)
                 </listitem>
             </itemizedlist>
         </para>
+        <note>
+          The "&amp;" character as well as numerical HTML entities like "&amp;#123;" are supported
+          in the contents. Literal HTML entities like "&amp;acute;" are not accepted. Please use
+          directly the UTF-8 character like "é" instead.
+        </note>
         <para>
         </para>
     </refsection>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0.1</revnumber>
+                <revdescription>
+                  Numerical HTML entities like <literal>&amp;#969;</literal> are now accepted in
+                  heading comments.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index e0db324..023cb5a 100644 (file)
@@ -1,40 +1,43 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <!--
  *
  * This help file was generated from help_from_sci.sci using help_from_sci().
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="help_from_sci" xml:lang="pt">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="help_from_sci" xml:lang="pt">
     <refnamediv>
         <refname>help_from_sci</refname>
-        <refpurpose>Geração de arquivos de ajuda e de arquivos de demonstração a
-            partir da seção de comentários de cabeçalho de um arquivo-fonte
+        <refpurpose>Geração de arquivos de ajuda e de arquivos de demonstração a
+            partir da seção de comentários de cabeçalho de um arquivo-fonte
             .sci
         </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
+        <title>Seqüência de Chamamento</title>
         <synopsis>
-            help_from_sci() // gera um modelo de função vazio
+            help_from_sci() // gera um modelo de função vazio
             help_from_sci(funname,helpdir) // gera helpdir/funname.xml a partir de funname.sci
             help_from_sci(dirname,helpdir) // processa dirname/*.sci e cria helpdir/*.xml.
-            help_from_sci(dirname,helpdir,helpdir) // como acima, mas também cria o arquivo de demonstração helpdir/*.dem.sce.
+            help_from_sci(dirname,helpdir,helpdir) // como acima, mas também cria o arquivo de demonstração helpdir/*.dem.sce.
             [helptxt,demotxt]=help_from_sci(funname) // retorna funname.xml e funname.dem.sce como duas matrizes de texto.
         </synopsis>
     </refsynopsisdiv>
     <refsection>
-        <title>Parâmetros</title>
+        <title>Parâmetros</title>
         <variablelist>
             <varlistentry>
                 <term>funname:</term>
                 <listitem>
-                    <para>o nome de um único arquivo .sci a ser processado</para>
+                    <para>o nome de um único arquivo .sci a ser processado</para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>dirname:</term>
                 <listitem>
-                    <para>nome do diretório onde todos os arquivos .sci serão
+                    <para>nome do diretório onde todos os arquivos .sci serão
                         processados
                     </para>
                 </listitem>
@@ -42,7 +45,7 @@
             <varlistentry>
                 <term>helpdir:</term>
                 <listitem>
-                    <para>endereço opcional onde o arquivo de ajuda .xml será
+                    <para>endereço opcional onde o arquivo de ajuda .xml será
                         criado
                     </para>
                 </listitem>
             <varlistentry>
                 <term>demodir:</term>
                 <listitem>
-                    <para>endereço opcional onde os arquivos de demonstração .dem.sce
-                        serão criados baseados nos códigos da seção Examples
+                    <para>endereço opcional onde os arquivos de demonstração .dem.sce
+                        serão criados baseados nos códigos da seção Examples
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>helptxt:</term>
                 <listitem>
-                    <para>retorna o código da ajuda XML se helpdir for vazio, ou o
-                        endereço para o novo arquivo .xml
+                    <para>retorna o código da ajuda XML se helpdir for vazio, ou o
+                        endereço para o novo arquivo .xml
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>demotxt:</term>
                 <listitem>
-                    <para>retorna o código de demonstração se demodir for vazio, ou o
-                        endereço para o novo arquivo .dem.sc
+                    <para>retorna o código de demonstração se demodir for vazio, ou o
+                        endereço para o novo arquivo .dem.sc
                     </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
-        <title>Descrição</title>
-        <para>help_from_sci é uma versão revisada da função help_skeleton. Seu
-            objetivo é gerar arquivos de ajuda .xml baseados na seção de comentários
-            de cabeçalho dos arquivos-fontes .sci. Opcionalmente, os arquivos de
-            demonstração .dem.sce podem ser gerados baseados nos códigos da seção
-            Examples na seção de cometários de cabeçalho dos arquivos .sci.
+        <title>Descrição</title>
+        <para>help_from_sci é uma versão revisada da função help_skeleton. Seu
+            objetivo é gerar arquivos de ajuda .xml baseados na seção de comentários
+            de cabeçalho dos arquivos-fontes .sci. Opcionalmente, os arquivos de
+            demonstração .dem.sce podem ser gerados baseados nos códigos da seção
+            Examples na seção de cometários de cabeçalho dos arquivos .sci.
         </para>
         <para>Para que help_from_sci formate o arquivo .xml propriamente, os a
-            seção de comentários de cabeçalho deve concordar com algumas regras
-            simples de formatação.
+            seção de comentários de cabeçalho deve concordar com algumas regras
+            simples de formatação.
         </para>
-        <para>A primeira linha de comentário seguinte à definição de função deve
-            conter uma descrição breve da função.
+        <para>A primeira linha de comentário seguinte à definição de função deve
+            conter uma descrição breve da função.
         </para>
-        <para>Os comentários restantes são formatados de acordo com os seguintes
-            cabeçalhos (opcionais): "Syntax", "Parameters", "Description",
+        <para>Os comentários restantes são formatados de acordo com os seguintes
+            cabeçalhos (opcionais): "Syntax", "Parameters", "Description",
             "Examples", "See also", "Used functions", "Authors" e
             "Bibliography".
         </para>
         <para>As seguintes diretrizes devem ser seguidas ao se escrever os
-            comentários de código fonte:
+            comentários de código fonte:
         </para>
         <itemizedlist>
             <listitem>
             <listitem>
                 <para>
                     <literal>Parameters</literal>
-                    - separe o nome do parâmetro e a descrição por um ":". Mantenha a descrição de cada parâmetro na mesma linha.
+                    - separe o nome do parâmetro e a descrição por um ":". Mantenha a descrição de
+                      cada parâmetro na mesma linha.
                 </para>
             </listitem>
             <listitem>
                 <para>
                     <literal>Description</literal>
-                    - a formatação do texto pode ser feita utilizando comandos XML. Adicionar uma linha de comentário vazia na seção Description é interpretado como começo de um novo parágrafo.
+                    - a formatação do texto pode ser feita utilizando comandos XML. Adicionar uma
+                      linha de comentário vazia na seção Description é interpretado como começo de
+                      um novo parágrafo.
                 </para>
             </listitem>
             <listitem>
                 <para>
                     <literal>See also</literal>
-                    - liste um nome de função por linha.
+                    - liste um nome de função por linha.
                 </para>
             </listitem>
             <listitem>
                 <para>
                     <literal>Authors</literal>
-                    - escreva um autor em cada linha após o cabeçalho Authors. Use ";" para separar os autores de qualquer informação adicional.
+                    - escreva um autor em cada linha após o cabeçalho Authors. Use ";" para separar
+                      os autores de qualquer informação adicional.
                 </para>
             </listitem>
             <listitem>
                 <para>
                     <literal>Bibliography</literal>
-                    - escreva uma referência por linha seguindo o cabeçalho References.
+                    - escreva uma referência por linha seguindo o cabeçalho References.
                 </para>
             </listitem>
         </itemizedlist>
+        <note>
+          The "&amp;" character as well as numerical HTML entities like "&amp;#123;" are supported
+          in the contents. Literal HTML entities like "&amp;acute;" are not accepted. Please use
+          directly the UTF-8 character like "é" instead.
+        </note>
         <para/>
     </refsection>
     <refsection>
         <title>Exemplos</title>
         <programlisting role="example"><![CDATA[
-help_from_sci()   // abrindo um modelo de código-fonte vazio no editor.
-// salve este modelo como test_fun.sci no diretório corrente antes de executar
-// os próximos comandos do exemplo
+help_from_sci()   // abrindo um modelo de código-fonte vazio no editor.
+// salve este modelo como test_fun.sci no diretório corrente antes de executar
+// os próximos comandos do exemplo
 
 help_from_sci('test_fun')        // retornando o esqueleto xml como um string de texto.
 
-help_from_sci('test_fun','.')    // criando o arquivo de ajuda xml no diretório corrente.
+help_from_sci('test_fun','.')    // criando o arquivo de ajuda xml no diretório corrente.
 
-// criando ambos os arquivos de ajuda e demonstração no diretório corrente.
+// criando ambos os arquivos de ajuda e demonstração no diretório corrente.
 help_from_sci('test_fun','.','.')
 
-// de um diretório raiz de um toolbox, uma seqüência de chamamento típica seria:
+// de um diretório raiz de um toolbox, uma seqüência de chamamento típica seria:
 // help_from_sci('macros','help\pt_BR','demos')
-// este comando processaria todos os arquivos .sci no diretório de macros
-// e utilizaria a seção de comentários de cabeçalho para atualizar as ajudas .xml no
-// diretório help\en_US e reconstruiria os arquivos .dem.sce no diretório demos\.
+// este comando processaria todos os arquivos .sci no diretório de macros
+// e utilizaria a seção de comentários de cabeçalho para atualizar as ajudas .xml no
+// diretório help\en_US e reconstruiria os arquivos .dem.sce no diretório demos\.
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
-        <title>Ver Também</title>
+        <title>Ver Também</title>
         <simplelist type="inline">
             <member>
                 <link linkend="help">help</link>
@@ -171,4 +183,16 @@ help_from_sci('test_fun','.','.')
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>Histórico</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0.1</revnumber>
+                <revdescription>
+                  Numerical HTML entities like <literal>&amp;#969;</literal> are now accepted in
+                  heading comments.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index 60cb920..3cf1fd7 100644 (file)
@@ -240,6 +240,7 @@ function [helptxt,demotxt]=help_from_sci(funname,helpdir,demodir)
     line = mgetl(f,1);
     line = replaceTabBySpace(line);
     short_descr = stripblanks(strsubst(line, "//", ""), %T);
+    short_descr = helpfromsci_protects_ampersand(short_descr);
     helptxt = [helptxt;
     "  <refnamediv>"
     "    <refname>"+out+"</refname>"
@@ -248,7 +249,7 @@ function [helptxt,demotxt]=help_from_sci(funname,helpdir,demodir)
     ];
 
     cmds = ["SYNTAX", "PARAMETERS", "DESCRIPTION", "EXAMPLES", "SEE ALSO", ..
-    "AUTHORS", "BIBLIOGRAPHY", "USED FUNCTIONS"];
+            "AUTHORS", "BIBLIOGRAPHY", "USED FUNCTIONS" ];
 
     doing = "search";
     i = strindex(line, "//");
@@ -268,7 +269,9 @@ function [helptxt,demotxt]=help_from_sci(funname,helpdir,demodir)
             in = stripblanks(in(2));
             code = in;  // store original line for the demos.
             if (doing ~= "Examples") then // Replacing characters like <, > or & should not be done in the Examples
-                in = strsubst(in, "&", "&amp;"); // remove elements that make xml crash.
+                // Replacing "&" that are not prefixing HTML entities, with "&amp;":
+                in = helpfromsci_protects_ampersand(in);
+                //
                 in = strsubst(in, "< ", "&lt; ");
                 if strindex(in ,"<") then
                     if ~helpfromsci_isxmlstr(in) then
@@ -302,8 +305,12 @@ function [helptxt,demotxt]=help_from_sci(funname,helpdir,demodir)
                         par_name = in;
                         par_descr = " ";
                     end
-                    helptxt = [helptxt; "   <varlistentry><term>" + par_name + "</term>"];
-                    helptxt = [helptxt;"      <listitem><para>" + par_descr + "</para></listitem></varlistentry>"];
+                    helptxt = [helptxt
+                               "        <varlistentry>"
+                               "            <term>" + par_name + "</term>"];
+                    helptxt = [helptxt
+                      "            <listitem><para>" + par_descr + "</para></listitem>"
+                      "        </varlistentry>"];
                 end
             elseif doing == "Description" & in == "new_descr_param" then
                 helptxt = [helptxt;"   </para>";"   <para>"];
@@ -378,6 +385,15 @@ function [helptxt,demotxt]=help_from_sci(funname,helpdir,demodir)
     end
 endfunction
 //==============================================================================
+function str = helpfromsci_protects_ampersand(str)
+    // Replaces "&" that are not prefixing HTML entities, with "&amp;":
+    strPrev = "";
+    while str ~= strPrev
+        strPrev = str;
+        str = strsubst(str, "/&(?!([a-zA-Z]+|#[0-9]+);)/", "&amp;", "r");
+    end
+endfunction
+//==============================================================================
 function tf = helpfromsci_isxmlstr(str)
     // Returns %t if the current string is a xml line
     if ( ~isempty(regexp(str, "/\<*[a-z]\>/")) ) then
diff --git a/scilab/modules/helptools/tests/nonreg_tests/bug_6911.tst b/scilab/modules/helptools/tests/nonreg_tests/bug_6911.tst
new file mode 100644 (file)
index 0000000..9a5a0fc
--- /dev/null
@@ -0,0 +1,23 @@
+// =============================================================================
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) 2017 - Samuel GOUGEON
+//
+//  This file is distributed under the same license as the Scilab package.
+// =============================================================================
+//
+// <-- NO CHECK REF -->
+//
+// <-- Non-regression test for bug 6911 -->
+//
+// <-- Bugzilla URL -->
+// http://bugzilla.scilab.org/6911
+//
+// <-- Short Description -->
+// Numerical HTML entities like "&#123;" were not supported in .sci heading comments
+// to be processed with help_from_sci()
+
+path = pathconvert(TMPDIR+"/bug_6911/help",%t,%t);
+mkdir(path);
+scifile = pathconvert(SCI+"/modules/helptools/tests/nonreg_tests/bug_6911_entities_in_sci_help.sci",%f,%t);
+assert_checktrue(execstr("help_from_sci(scifile, path)", "errcatch")==0);
+assert_checktrue(execstr("xmltohtml(path)", "errcatch")==0);
diff --git a/scilab/modules/helptools/tests/nonreg_tests/bug_6911_entities_in_sci_help.sci b/scilab/modules/helptools/tests/nonreg_tests/bug_6911_entities_in_sci_help.sci
new file mode 100644 (file)
index 0000000..b53e92a
--- /dev/null
@@ -0,0 +1,32 @@
+// =============================================================================
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) 2017 - Samuel GOUGEON
+//
+//  This file is distributed under the same license as the Scilab package.
+// =============================================================================
+function  [s, v] = entities_in_sci_help(r,t)
+    // Tests if entities like &#969; are supported & kept unconverted.
+    // Calling Sequence
+    //   [surface, volume] = entities_in_sci_help(r,t)
+    //
+    // Parameters
+    //  r: vector of pulsations &#969;
+    //  t: vector of theta angles of the mesh
+    //
+    // Description
+    // Direct UTF-8 characters like "âäéèêë" & "ìïôöòûüùñ" are supported.
+    // Literal HTML entities starting with & + letters + ; are not accepted.
+    //
+    // Examples
+    //// This is an omega &#969; & here is a &eacute;
+    //    r = linspace(1,2,30); t = linspace(0,2*%pi,100);
+    //
+    // See also
+    //  help_from_sci
+    //
+    // Authors
+    //  Samuel GOUGEON
+    //
+    s = 1;
+    v = 2;
+endfunction