Re: [help-texinfo] attribute ‘number’

[Patrice Dumas]

On Sun, Mar 01, 2015 at 04:36:34PM +0000, Gavin Smith wrote:
> On 1 March 2015 at 11:42, Thien-Thi Nguyen <address@hidden> wrote:
> > I see the source (also in Parser.pm) of that subroutine is:
> >
> >  # return true if effect of global commands should be ignored.
> >  sub _ignore_global_commands($)
> >  {
> >    my $self = shift;
> >    return !$self->{'expanded_formats_stack'}->[-1];
> >  }
> >
> > but before i wade in fully, i'll just ask quickly here: What
> > must the user do (in terms of command-line options) to affect
> > the ‘expanded_formats_stack’?
> 
> My understanding is that this is used to ignore some commands, such as
> index commands, and other commands that record information that is not
> local to where the command occurred, like "@setfilename". This is in
> effect while inside a "raw formatter command", like @html, to include
> raw HTML in a Texinfo file. Presumably there is still some Texinfo
> parsing still being done while inside these commands, though.

Unless I don't recall well, it is not when in a raw formatted command,
but in an ignored raw formatted command.  It also includes @inlinefmt
and similar @-command.  So, for example when generating Info everything
in @html is parsed, but _ignore_global_commands will return true 
when in @html or @inlinefmt{html} such that those @-commands have no
effect.  @html will still appear in the tree.

> this, or indeed what using e.g. "@cindex" within "@html" should mean.
> However, this will not make the index entry show up in the indices
> when they are output with @printindex.

In the 5.0 release it was aggreed that @-commands in raw format blocks
such as @html would be treated as usual.  So, when generating html
(or with --ifhtml)

 @html
 in html
 
 @cindex a word
 @end html

"a word" will appear in printindex, but not when generating Info.

> > (I'm trying to figure out what
> > the IXIN stance towards attribute ‘number’ should be: ignore,
> > require, support but not require.  I didn't find any mention of
> > ‘number’ in the NEWS file, although i did find address@hidden number’ in
> > node "Customizing Output File Names" in doc/texi2oldapi.texi,
> > which seems obsolete or on its way to being so...)
> 
> I'd suggest not adding data to the output formats unless there is a
> real use for it. Otherwise it is a burden on the other code in
> texi2any/makeinfo to pass along the information required to output
> this information. I don't know what the "number" attribute is used for
> in the XML output, but I don't know what the XML output as a whole is
> used for anyway.

It is used to provide with an equivalent representation of the .texi,
although with user @-macro and @value and similar expanded.  It was used
previously to convert to other formats (there was aa converter to LaTeX
based on the TexinfoXML output in the past).  The SXML output is based
on the same code, so embeds the same information.

> The use of the 'expanded_formats_stack' in the Parser.pm module is not
> very related to the question of whether a "number" attribute is
> needed. 

It may, as the "number" being present is a marker of the @-command being
in an ignored raw section or not.

> A more important question would be what to do with index
> commands within blocks like @html where they don't lead to an index
> entry. My first reaction would be to ignore them, because I can't
> think of a use for them off the top of my head, although there is
> always a chance there is one I've missed.

No, I think you are right -- at least when not doing html.

When doing an intermediary format such as Texinfo XML, or SXML, for 
example for IXIN, but more generally for any other user of intermediary
format, it is less obvious what to do with global @-commands in that
case.  I think tht the best would probably be to ignore them too, but
more generally ignore the whole block and not only he index entry.
Indeed, the usual practice is that the raw block commands are redundant,
so only having one expand seems the best.

So, when doing XML in general, and in particular for IXIN, either the
document has provision for XML with specific @xml raw blocks or the user
calling makeinfo to provide XML/SXML or directly IXIN should choose
appropriately an --ifformat.

-- 
Pat