texinfo (was: update contribute.html for regression testing)

[Gerald Pfeifer <pfeifer at dbai dot tuwien dot ac dot at>]

This dwelled in my postponed folder quite some time. Keep in mind that
``now'' is November 2000.

On Tue, 7 Nov 2000, Jeffrey A Law wrote:
>>> Someone also needs to look at the instructions in the info manual
>>> (gcc.texi) on sending patches (e.g. sending each logically separate patch
>>> separately), merge them into contribute.html and make the info manual
>>> point to contribute.html.
>> Yet another reason to do everything in texinfo and use texi2html to
>> generate the web pages.
> Agreed.
Joe> I'd prefer to have it all in texinfo, but I'm not going to go
Joe> to war over it.
Mark> That sounds like my position as well.  I'd prefer to have everything
Mark> in TeXinfo -- but I have insufficient energy or conviction to make
Mark> an issue of it. :-)


Folks, I think we are dealing with several issues here. The following is
a bit long, but hopefully makes the situation somewhat clearer.


1. We have redundant (and obsolete) information spread over the place:
Bug reporting instructions, what Joseph mentioned above, etc. etc.

Joseph, myself and others are working to detect and address such cases
and we have been rather successful recently, I'd say. :-)


2. Some stuff, like the main page or news.html are impossible (or at least
hard) to maintain properly using texinfo and texinfo2html; in other cases
like lists.html or search.html it really doesn't make sense to do so.

So having "everything in texinfo and [using] texi2html" does not sound
like a viable approach.


3. Some of the information mentioned under 1. is in various formats:
Texinfo, ASCII, HTML.

For historical reasons -- that to a large extent predate me becoming web
pages maintainer -- there are many cases where we have obsolete
information in texinfo format, where the current version is in HTML.

In several cases, like the bug reporting instructions, it seems that
the proper place for these is on the web anyway (considering gnats(web),
for example, or the mailing lists page).

texinfo is great tool for longer documents, but I really don't think it is
suitable for single web pages (which the page at hand, cvswrite.html, is).


4. The installation documentation is a specific case, where it would
constitute a *change* in policy to switch to texinfo.

Originally in texinfo format, the official installation documentation for
egcs 1.0, egsc 1.1 and GCC 2.95 has been the HTML one.

I do not object having installation documentation in texinfo and
generating HTML from that at all(!). It's just that I do not have the
capacity to do this by myself anytime soon as I've already been spending
too much time for GCC lately and there still are some issues Mark
considered very important and that are thus at the head of my queue.

Plus, frankly, I'm not extremely motivated either, as I already had a
first version in my hands but [you know the story]...

Now, if we had a volunteer, I'd certainly be willing to take care of
reviewing and implementing everything required.


5. It's not that easy

...when it comes to mirror sites, immediate updates. And also making the
change outlined in 4. is quite a bit of work, in terms of writing docs
and several scripts.

Gerald
-- 
Gerald "Jerry" pfeifer@dbai.tuwien.ac.at http://www.dbai.tuwien.ac.at/~pfeifer/