Is @caption mature?

[Akim Demaille]

I'm very happy to see the introduction of float, caption, and
listoffloats.  Nevertheless, for the time being the result is not as
good as what was obtained with a macro, and some assistance from Emacs
to renumber automatically @filecaption etc.

Given:


: -------------------- captions.texi ----------------------
cat > captions.texi << \EOF
\input texinfo   @c -*-texinfo-*-

@c filecaption(ORDINAL, NAME)
@c ==========================
@macro filecaption{ordinal, name}
@anchor{Example address@hidden \ordinal\}: @file{\name\}
@end macro


Compare this:

@float File, simple-fact.tig
@example
/* Define a recursive function. */
let
  /* Calculate n!. */
  function fact (n : int) : int =
    if  n = 0
      then 1
      else n * fact (n - 1)
in
  fact (10)
end
@end example
@address@hidden
@end float

@noindent
and the following.

@example
/* Define a recursive function. */
let
  /* Calculate n!. */
  function fact (n : int) : int =
    if  n = 0
      then 1
      else n * fact (n - 1)
in
  fact (10)
end
@filecaption{1, simple-fact.tig}
@end example

@bye
EOF
: ------------------------------------------------------------


On text output, there is an additional empty line, and an increased
loss of text width:

src/texinfo/test-cases % makeinfo --no-header < captions.texi    nostromo 14:37
Compare this:

          /* Define a recursive function. */
          let
            /* Calculate n!. */
            function fact (n : int) : int =
              if  n = 0
                then 1
                else n * fact (n - 1)
          in
            fact (10)
          end

     File 0.1: `simple-fact.tig'

and the following.

     /* Define a recursive function. */
     let
       /* Calculate n!. */
       function fact (n : int) : int =
         if  n = 0
           then 1
           else n * fact (n - 1)
     in
       fact (10)
     end
     *File 1*: `simple-fact.tig'


For HTML, the output is not better either IMHO:

captions.html.png
Description: PNG image

And finally, the TeX output is nice, but I miss the bold face.  I
suppose the message are just debugging?


src/texinfo/test-cases % texi2dvi captions.texi                  nostromo 14:42
This is e-TeXk, Version 3.14159-2.1 (Web2C 7.4.5)
 file:line:error style messages enabled.
entering extended mode
(/home/akim/src/texinfo/test-cases/captions.texi
(/usr/local/share/texmf/tex/texinfo.tex
Loading texinfo [version 2004-02-19.09]: Basics, pdf, fonts, page headings,
tables, conditionals, indexing, sectioning, toc, environments, defuns, macros,
cross references, insertions, (/usr/share/texmf/tex/generic/dvips/epsf.tex)
localization, and turning on texinfo input format.)
@xrdef{ simple-fact.tig-title}{!!float!!=File}
@xrdef{ address@hidden 1}
@xrdef{ address@hidden 1: @file {simple-fact.tig}}
@xrdef{Example 1-title}{}
@xrdef{Example 1-snt}{}
[1
@xrdef{ simple-fact.tig-pg}{1}
@xrdef{Example 1-pg}{1}
] )
Output written on captions.dvi (1 page, 892 bytes).
Transcript written on captions.log.



Also, note that:

@float File, simple-fact.tig
@example
@address@hidden
@end example
@end float

is ok by makeinfo, but not with TeX (i.e., the @caption is directly
inside @example):

/home/akim/src/texinfo/test-cases/captions.texi:24: This command can appear onl
y in environment @float, not in environment @example