Re: documentation needed

[Patrice Dumas]

On Thu, Sep 15, 2011 at 11:17:54PM +0000, Karl Berry wrote:
>     Now that the Parser is done
> 
> Well, that is great!
> 
> So how does all the user-level Perl customization that are in
> texinfo.txi relate to reality now?  Seems to me we do have to document
> that in the user manual ...

First for the customization variables, the following are not
relevant for now

ENCODING_NAME I18N_PERL_HASH IGNORE_PREAMBLE_TEXT IN_ENCODING L2H* 
NEW_CROSSREF_STYLE SEPARATE_DESCRIPTION SPLIT_INDEX USE_NLS USE_UNICODE 
WORDS_IN_PAGE

I think that we can 
* remove things that have no reason to exist anymore
  I18N_PERL_HASH IGNORE_PREAMBLE_TEXT NEW_CROSSREF_STYLE USE_NLS USE_UNICODE 
SEPARATE_DESCRIPTION

* comment out things that could reappear some day
  ENCODING_NAME  IN_ENCODING L2H* SPLIT_INDEX WORDS_IN_PAGE

Now for the customization part, I think that for now we should just
put that in a big ignore block and wait a bit before documenting
the things documented in there.  It looks like a step behind, but, in my 
opinion, it is not.  Indeed, what could now be documented is that part
of the API that is consistent and should not change anymore, which is
all the function references that may be used to customize how a
tree element is formatted.  It corresponds to some extend to 
what is in texi2oldapi.texi.  But what is currently in texinfo.txi 
is that part of the API that I am still not satisfied with and will 
certainly need lots of reworking before coming to something satisfying.
Maybe more than reworking, what is needed is a design of that part of 
the API that is as nice as the other part.

Also, I don't think that documenting that API is a priority nor that it
should delay the release.  For one thing I would prefer first to use 
it myself for the rewrite of relevant init files, to see if it is a 
good API and how it should be changed.  Also I would like to see 
what happens for the transition of init files done for lilypond.
And then I think that the documentation of the modules and the pod2texi 
stuff is much more important, and I would even think that other activities 
(that are still mysterious at that day since the videos are still not up at 
the GHM site and therefore I still haven't made the report on the texinfo 
mailing list ;-) should be done in priority over this HTML customization 
interface documentation.



I have also seen some things here and there in the manual that needs to 
be modified (like texi2any now produces info in the default case, new 
customization variables, remove references to init files for now unless 
I have time to rewrite them...), I can take care of that.

-- 
Pat