proposals of change for INTRODUCTION and Overview of Texinfo

[Patrice Dumas]

Hello,

I have reread a bit the documentation and I have several remarks.
Of course I can turn those remarks to patches (that would have to 
be proofread)!

On INTRODUCTION
===============

First the INTRODUCTION file seems to me to be quite out of date, not
in line with current ways and quite confusing.  In fact it is very
unclear to me who this file targets.

If it targets users downloading the texinfo sources, it is a bit
strange, because it assumes that the reader will be able to generate
the Texinfo manual, compile and install the info program without
having read instructions on how to do it.  So, it seems to me
that (after a paragraph on Texinfo and maybe another on the info
reader) the reader should read the INSTALL.generic file.  In that
case, I think that it would be better to add those paragraphs to the
README instead of having an INTRODUCTION file.  Informations on reading
the in source documentation could then follow, in the README.

If the INTRODUCTION file is meant for people that already have a Texinfo
working installation (installed by a sysadmin, or as part of a GNU/linux
distro or whatever), then I think the 'Overview of Texinfo' chapter
of the Texinfo manual does a better job as a tutorial than 
INTRODUCTION.  In that case, the INTRODUCTION should, in my opinion 
only be used to explain how get hands on the Texinfo manual (after one
paragraph or two on what is Texinfo).  So, in my opinion, it should 
point to the Texinfo manual on the web in HTML and pdf, explain how 
to get acquainted with the info format with info info or the Emacs 
Info reader and that, once acquainted, should run info texinfo.

On the 'Overview of Texinfo'
============================

I think that the 1.1 'Reporting Bugs' should better at the end of
'Overview of Texinfo', before the History.  I also think that the 
second part of the '1.3 Output Formats', beginning with 'From time 
to time, proposals ...' should be in a separate section, and appear 
later, could be called 'Adding additional output formats', and 
appear between 'Reporting Bugs' and 'History'.

I also think that the '1.4 Info Files' is too long and should be more
oriented towards Texinfo than towards Info for the first half.  First
it duplicates some information from 'Output Formats' but more
importantly I think that the chapter like structuring should be 
described, then it should be explained that it should be doubled 
with a node and menu structure for Info and HTML.  Then the second 
part of the node starting with 'Generally, you enter an Info file 
through ...' would follow unchanged.

I think that the sixth paragraph of '1.5 Printed Books' should be
removed, as texinfo.tex do not allow much customization.  I don't know
how to 'make a book look dignified, old and serious, or light-hearted,
young and cheery.' with texinfo.tex (but maybe I am missing something).

The last paragraph of '1.8 Comments' should be removed, in my opinion,
it is much too early for such information, and it is mostly incorrect,
at least for makeinfo.  A correct explanation of limitations is in
'18.6 Conditional Nesting', much more at the proper place in my
opinion.





Last, everytime the Texinfo format is presented, the feature put forward
is the possibility to generate different outputs from one unique source.
I think that there are 2 other features that are worth mentioning: the
fact that it is based on semantic markup, and use only @-commands and 
braces.  Should we change that in some places?

-- 
Pat