[octave forge] (generate_html) fprinf failure during html generation

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[octave forge] (generate_html) fprinf failure during html generation

JuanPi
Hi all,
I am preparing the release of matgeom and geomtry and when I am trying
to generate the html for matgeom I get

> pkg load generate_html
> generate_package_html ("matgeom", "OF/matgeom-html", "octave-forge");
error: fprintf: invalid format specified
error: called from
    generate_package_html>fileprintf at line 833 column 5
    generate_package_html>process_alpha_tree at line 746 column 5
    generate_package_html>process_alpha_tree at line 740 column 7
    generate_package_html at line 293 column 5

I have not been able to identify the source of the problem in the
unwieldy generate_package_html.m
It seems to fail while processing geom3d/cart2cyl.m, but I can't see
any problem in the docstring of that function.

Any suggestions?

--
JuanPi Carbajal
https://goo.gl/ayiJzi

-----
“An article about computational result is advertising, not
scholarship. The actual scholarship is the full software environment,
code and data, that produced  the  result.”
- Buckheit and Donoho

Reply | Threaded
Open this post in threaded view
|

Re: [octave forge] (generate_html) fprinf failure during html generation

Mike Miller-4
On Mon, May 13, 2019 at 23:45:49 +0200, JuanPi wrote:
> Hi all,
> I am preparing the release of matgeom and geomtry and when I am trying
> to generate the html for matgeom I get
>
> > pkg load generate_html
> > generate_package_html ("matgeom", "OF/matgeom-html", "octave-forge");
> error: fprintf: invalid format specified

In the context of printf-style functions, the term "invalid format"
usually means that an unescaped percent character is part of the
template string. Typically, this means the printf function is called
incorrectly with unsafe input, for example

    printf (my_string);

instead of

    printf ("%s", my_string);

So this is a bug in the generate_html package, when the first help
sentence of a function contains a literal '%' character.

A simple test case would be

    ## -*- texinfo -*-
    ## @deftypefn {} {} myfunc
    ## This function is 10% ready.
    ## @end deftypefn
    function myfunc ()
    endfunction

I can reproduce the exact error with a trivial package containing this
function.

So actions to move forward from here

1. file or fix the bug in generate_package_html
2. see if it's easy to avoid using '%' in function doc strings

I notice that matgeom in particular uses Matlab-style help blocks, and
typically does not end the first line with a period. So you may find
that none of the first lines of all doc strings have a percent, but
Octave will read multiple lines until it sees a period. Look at

    get_first_help_sentence ('circle3dPoint', 200)

for an example from your package that returns much more than a summary
sentence, and includes a '%' character that triggers this error.

--
mike

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [octave forge] (generate_html) fprinf failure during html generation

JuanPi
Hi Mike,

Thanks a lot for investing time on this.

The whole effort to separate matgeom form geometry was exactly to
avoid editing the upstream code, sync becomes a real issue.
I could imagine however that a hook when merging from upstream could
be used to replace all % with #, being careful not to replace inside
format strings and such.
I would rather avoid doing this if possible, but if there is no other way...

On the other hand, generate_html should be tolerant to the % symbol,
so I filed the bug.

Regarding the issue with the sentences, I will report to upstream, see
if they accept it (I do not see why they wouldn't)

Thanks!


On Tue, May 14, 2019 at 12:44 AM Mike Miller <[hidden email]> wrote:

>
> On Mon, May 13, 2019 at 23:45:49 +0200, JuanPi wrote:
> > Hi all,
> > I am preparing the release of matgeom and geomtry and when I am trying
> > to generate the html for matgeom I get
> >
> > > pkg load generate_html
> > > generate_package_html ("matgeom", "OF/matgeom-html", "octave-forge");
> > error: fprintf: invalid format specified
>
> In the context of printf-style functions, the term "invalid format"
> usually means that an unescaped percent character is part of the
> template string. Typically, this means the printf function is called
> incorrectly with unsafe input, for example
>
>     printf (my_string);
>
> instead of
>
>     printf ("%s", my_string);
>
> So this is a bug in the generate_html package, when the first help
> sentence of a function contains a literal '%' character.
>
> A simple test case would be
>
>     ## -*- texinfo -*-
>     ## @deftypefn {} {} myfunc
>     ## This function is 10% ready.
>     ## @end deftypefn
>     function myfunc ()
>     endfunction
>
> I can reproduce the exact error with a trivial package containing this
> function.
>
> So actions to move forward from here
>
> 1. file or fix the bug in generate_package_html
> 2. see if it's easy to avoid using '%' in function doc strings
>
> I notice that matgeom in particular uses Matlab-style help blocks, and
> typically does not end the first line with a period. So you may find
> that none of the first lines of all doc strings have a percent, but
> Octave will read multiple lines until it sees a period. Look at
>
>     get_first_help_sentence ('circle3dPoint', 200)
>
> for an example from your package that returns much more than a summary
> sentence, and includes a '%' character that triggers this error.
>
> --
> mike



--
JuanPi Carbajal
https://goo.gl/ayiJzi

-----
“An article about computational result is advertising, not
scholarship. The actual scholarship is the full software environment,
code and data, that produced  the  result.”
- Buckheit and Donoho