Re: a tentative plan for the after release

[Patrice Dumas]

On Tue, Feb 19, 2013 at 02:14:39PM +0000, Karl Berry wrote:
> Getting back to your mail from last September (appended for convenience)
> now that the release is, finally, out.
> 
>     1.a settle on the fate of Info versus HTML/Docbook/sexp-based output
> 
> Info is not going away in the foreseeable future, as far as I can see.

Indeed. Ixin is certainly a way forward, but will not replace Info in a
foreseable future.

>         and, if Info is retained as is, decide how things should be
>         escaped in node and cross-ref names
> 
> Granted that we should do this, I don't know that it is a top priority.
> People have been living with the restrictions on names, silly as they
> are, since day one.

If we begin to do more automatic translation to Texinfo, as is done by
pod2texi for instance, but also some automatic generation of nodes based
on section names, this becomes a huge issue.

>     1.b remove the need for an @iftex at the beginning of document.
>         Cf my mail on this list
> 
> Similarly as with previous item, granted it would be nice, it doesn't
> seem so critical to me.

I think it is very critical.  Because it is a prerequisite for thinking
about new backends, especially backends that are more on the 'book'
side, such as the LaTeX backend.  Right now it is not practical because
of that issue.  Also, I think this is an issue that could be easily 
solved and in a backward compatible way.

>     1.c determine how marksource material should appear in the tree (macro
>         begin and end expansion location, include files, @ at end of @def*
>         lines, etc.)
> 
> That one is for you, right?  I agree it's not urgent.

Indeed, it is for me.  This is not very urgent, but it would be nice to
have it right before finalizing the HTML customization API.

>     1.d add the possibility to add @-commands to be processed by the Parser
>         in customization files
> 
> That sounds awfully scary to me.  And those customization files aren't
> going to be read by TeX ...

Indeed, but this is something that have been used in the lilypond
customization.  This one is clearly not crucial, may be dangerous, and
not a priority.

>     1.e work with Guido on the customization of translations
> 
> Whatever is needed.  Translations in general are also not a top priority
> in my eyes.

This is also needed for the lilypond customizations, and I think that in
output document string customization will necessarily be part of the
customization API.  So, this is a prerequisite for HTML customization
API stabilization.

> The things that do seem like the most important to me, i.e., will have
> the greatest user impact, are:
> 
> 1) as you say, stabilize and document the API -- 

Ok, with the caveat that it depends on strings customization above.

> ideally not just about
> HTML output, either, but to the point where someone could feasibly write
> another backend.  Arnold Robbins keeps asking me about an nroff
> backend.  He knows nroff, but can't just look at the big mass of
> texi2any code and know where to dive in.

That part of the API is already stabilized, and documented (in a CPAN
man pages way, which may not be the best way, though).  It is more or
less the Texinfo::Common module, Texinfo::Convert::Unicode,
Texinfo::Report and Texinfo::Convert::Converter modules
for useful code, and the documentation in the Texinfo::Parser module for
the description of the tree.  So, this is clearly an issue orthogonal to
the HTML customization API issue.  I think that there is already
everything ready for a nroff backend, which should be a new backend,
(and would certainly be very similar with the DocBook backend).  Now,
the real issue is, do we want to do a real manual on writting a backend
for a new format?  The modules documentation is already in doc/tp_api/
but it could be complemented, or organized differently.  

My gut feeling, but I am certainly very biased, is that, in fact, there 
is already enough documentation to write a new backend, by using the
modules documentations for the API, and then the best documentation is 
the existing backends, with TextContent.pm and Texinfo.pm/PlainTexinfo.pm 
as examples of trivial backends, Text.pm an example of a less trivial 
but still simplistic backend, DocBook.pm a real converter not too complex 
and the others as specific and/or rather complex backends, too complex,
in fact, to be used as 'documenation' or starting points.  (I could 
add this sentence to the Texinfo::Convert::Converter module
documentation...).

> 2) the LaTeX backend; in practice, this is the only way we're going to
> get real UTF-8 etc. support in the TeX output.
> 
> So, hmm, this is a bit different from your priorities ... ?

It may be done rather rapidly, but it depends on the titlepage stuff.


Here is an updated program that hopefully is more consistent with what
you propose (with removal of what is already done):

1.a remove the need for an @iftex at the beginning of document.  Cf my
    mail on this list
1.b design how marksource material should appear in the tree (macro
    begin and end expansion location, include files, @ at end of @def*
    lines, etc.)

2.a (1.a) LaTeX backend
2.b work with Guido on the customization of translations

3.  (1.b, maybe 1.a, 2.b) stabilize the HTML customization API, document it

4.  protection in Info, design and implementation (with the main player
    here being the info reader, and, therefore, Sergey).

5.  actual implementation of marksource

6.a add the possibility to add @-commands to be processed by the Parser
    in customization files
6.b work on Ixin, finalize format and implementation

7.  (3., 6.a, 2.b) work on lilypond, to have lilypond use texi2any
      http://code.google.com/p/lilypond/issues/detail?id=1000

?.  manual on new backends coding


The objectives for the release would be up to 3., the remaining could be
postponed (although I will certainly work quite a bit on Ixin when I
have time).  For 4., there is mostly a need for Sergey input, I think
that texi2any part of the job may be done fairly rapidly.

Something that is also not for the next release, but certainly the one
after, is the speed optimization.  It depends on 5., and maybe on 6.a.

-- 
Pat