wwwdocs/htdocs/egcs-1.1/fortran.html

[craig@jcb-sc.com]

>>>>>> "Jeff" == Jeffrey A Law <law@hurl.cygnus.com> writes:
>
> Jeff> Well, instead of trying to convert this thing to html by hand
> Jeff> on a regular basis why don't we use texi2html so that we only
> Jeff> have a single news file instead of trying to maintain a copy in
> Jeff> the sources and another for the web pages/
>
>That's what my changes to the makefile and news0.texi were for.  I
>didn't know it was supposed to have the bug list too.  I can probably
>redo it for 1.2, given instructions.

I just threw the bug list in because I thought it was important to
have immediately available to web-browser types, and didn't see any
other obvious hook for it.

I'm still a bit concerned about any (semi-)automated process taking
over the job.  (I feel a *fully* automated process would necessarily
require complete integration of a bug-, patch-, and release-tracking
system, because....)  Ideally, a given release should document, in its
"news" and "known bugs" info, only the items that apply to that release.

Yet, also ideally, people enquiring about the overall product,
especially one still in multiple-life limbo-land like g77 (where
there's an egcs version and an FSF version), should be able to see
*all* the news and known-bugs info, across all the releases (or, at
least, the releases for which such info is supported).

For example, this could allow them to make more informed decisions
about what releases would be most appropriate for their various needs.
Whereas, people reading about a specific release wouldn't have to
parse what might look like a long known-bugs list to figure out
what is *not* already fixed in that release.  (Remember, we find out
about known bugs in releases *after* they're released.  In a very
small way, my fortran.html improvements embody this by putting
two new items in the known-bugs section.  Those bugs have already
been fixed in the trunk, for 1.2, but even though they're now "known"
for 1.1.2, they should be available to people reading up on 1.1 in
general.  Maybe even 1.0, though there are natural limits on how
far back we'd want any system -- whether automated, manual, or
in-between -- to try to research whether known bugs existed.)

For now, given that the automated tools we *do* have aren't capable
of handling this without us introducing, into the sources, way too much
"conditionals" cruft, I'm leaning towards preferring to use those
tools by hand, and then post-editing the results, for things like
producing the Web document that lists changes for a particular release.

When it comes to derived files like egcs/gcc/f/'s BUGS, INSTALL, NEWS,
and intdoc.texi (the last of which I wish we could get out of the
source distribution in the future, but can't remember why people need
it there offhand), the present automation makes sense (and works,
modulo the need to invoke it by hand and commit the resulting changes
to the repository).  That's because those files are designed to be
just nicely readable plain-text versions of the .texi files.

So, I wouldn't mind adding automation to provide .html versions of
those files in a suitable place.  Since I do try to keep the g77
doc sources up-to-date vis-a-vis checkins to the trunk, it'd be
kinda cool if the Web pages were automatically updated so people
could access the latest info on g77 improvements, perhaps from a
parent page called "Ongoing Unreleased Development Work".

(I have been thinking, for some time now, about what a much-more-fully-
automated system for managing all this would look like.  I'm considering
undertaking at least the R&D aspects of such a system, because I think
we might be getting to the point in the free-software community where
*not* having such a system keeps us from leaping past most other
forms of funding software development, if we haven't already reached
that point long ago.  My interest in this is part of why I try to
use the existing tools I believe such a system would obviate -- CVS,
diff, patch, email, etc. -- in a "straightforward", perhaps "naive",
fashion, to make sure I don't assume the present levels of knowledge
of vast amounts of technical trivia needed to operate the toolset
currently used to effect bazaar-style development when it comes to
designing something new.  This system can *not* be designed using
just the sort of hacker expertise that currently reigns in software
development.  It *must* be thoughtfully engineered, from first
principles, requirements, ergonomics, and so on, or it will be a
very expensive failure.)

Anyway, if you have ideas for the trunk, I'd appreciate it if you'd
first outline what they are generally supposed to accomplish, from
the views of various sorts of end users (including: people with
a release distribution but no net/web access; people exploring the
Web trying to figure out which release of a product is best for
them; people trying to figure out if the release they have has
been since discovered to have known bugs not documented in the
original release) and from us developers.

It's also been interesting to me to observe how more and more people
on the egcs projects are, in my estimation, converging on some kind
of wholesale solution to the documentation problem (which I personally
don't see clearly myself, at this point) -- ranging from the compiler
documentation all the way to the up-to-the-minute web pages.

In light of that, it might be wise to discuss various approaches first,
and do implementations later, so we don't end up playing whack-a-mole
with regard to the growing, and wide, set of opinions about requirements
for the doc set (which include ease of maintenance by developers, but
not as the only one!).

        tq vm, (burley)