On 10 April 2015 at 18:12, Kozma, Endre <address@hidden> wrote:
> Working on the next revision of the ngspice package I continuously suffer
> from makeinfo warnings. I tracked down the cause of the issue and I
> concluded the following:
>
> 1. The warnings are caused by the nested @deftypefn structures in one of my
> oct-files (I need to document some callback prototypes and I do it in this
> way).
> 2. The real problem however lays in the first_sentence_texinfo () function
> (get_first_help_sentence.m). Namely it removes all @def... lines but not all
> @end def... ones, but it removes everything from the first @end def.. line
> to the end of the help text potentially making erroneous texinfo data by
> that.
>
> My question is: if we simply remove all @def.. lines why don't we remove
> similarly all @end def.. lines? By this we'd end up having a valid texinfo
> data (assumed the original help text was valid) which wouldn't cause
> makeinfo warnings.
Why are you nesting deftypefn in the first place? I thought that was just
invalid syntax. I think you have to end one and then start another. See
for example the help text of gallery [1]. I believe this creates perfectly
valid texinfo data.
Carnë
[1] http://hg.savannah.gnu.org/hgweb/octave/file/b34a23c8a9c4/scripts/special-matrix/gallery.m
The parameters of the function to be documented are property string - function handle pairs, thus I discuss the prototype of these parameter functions in the "parameters" section within the outer @deftypefn. But I have to correct myself. The warnings are caused not or not only by the nested @deftypefn, but by the removed other @end ... lines (it discards the texinfo data from the first @end deftypefn to the end). So e.g. if your @deftypefn is inside a @table, then this implies that the @end deftypefn is followed by an @end table somewhere at the end of the text. But then this latter is removed by the first_sentence_texinfo function, which results in invalid texinfo data.
).