Re: wwwdocs/htdocs/egcs-1.1/fortran.html

[craig at jcb-sc dot com]

>  In message <19990227134631.26569.qmail@deer>you write:
>  > 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.
>I'd prefer a semi-automated job to one done totally by hand.  The more things
>we have to do by hand the more error prone the job will be and the more time
>that's taken away from other tasks.

I think what y'all have done (Gerald, Jeff, etc.) since my above-
quoted email is quite consistent with what I'd like to see,
without sacrificing things I want to preserve (like version-specific
docs targeting just that version).

>None of these schemes is completely automated, but each one takes a step
>forward by automating some significant set of tasks that a human used to take
>care of.

Yup.  But it takes a lot of high-level thinking about what the *purpose*
of the tasks (your mailing-list example, which I snipped, or handling
documentation of something as complex as egcs) to take these steps at
the *development* level.

What I was trying to get across in my email, not rather clearly I'm
afraid, is that, *before* we automate, let's *thing* about what
we're really trying to accomplish.

>Iterate and improve (majordomo+sendmail), know when to start over
>(ezmlm+qmail).  It's not significantly different from software engineering --
>know when to improve something (alias analysis) and when to throw it out and
>start again (configure/make subsystem).

(qmail strikes me as an example of a product that was created, from
scratch, by someone who *first* really learned about, and thought
through, what was really the true *purpose* of a MTA, by the way.
I'm using it on my LAN.  Not that I've done much in the way of comparison
shopping....)

>Given the volunteer, free-form nature of this project, I'd be very suprised
>if we could get a completely integrated, bug, patch & release tracking system
>together.  That's a tough problem, I know because I have to deal with these
>issues as part of my day job :-)

Right, I don't think that system should come from the egcs project,
as much as we'd like to drive that infrastructure.

But, I think the open-source community (perhaps just the GPL-development
community) would benefit *greatly* from such a system, if it was
properly thought through, designed, and implemented, a la qmail.

>  > 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.
>I would think just a @c egcs-1.1.1 or some other marker would be enough for
>perl to be able to do the right thing to pick out the stuff we want.  Or
>use menus in texinfo to get to each release.  I *think* texi2html is supposed
>to DTRT for texinfo menus.

I've been thinking about simple, clean ways to handle what I want to
be able to do with g77.

The best solution I can come up with is to have the trunk contain what
might be called the "living docs", which includes whatever fuzzy-state
relationships exist between the docs and the code, but in the news.texi
file, complete, up-to-date per-version information on *released* versions
(assuming the g77 people keep it up-to-date).

Then, when we make a branch for a release, the g77 folk update the
doc sources so these "know" they're for a specific release branch,
and update the news.texi file (chopping out subsequent trunk stuff
that isn't in the branch) and bugs.texi file (adding items about
bugs as they're found, and perhaps fixed, in the trunk, but not fixed
in the branch) appropriately.

I think I'm about ready to implement this.

The result should be that the trunk docs advertise themselves as
such, in the appropriate locations.  So, when they're pulled down
via a CVS read and printed out, or read "live" via your onlinedocs/
magic, people know they're "live" just like the trunk in the repository
itself is "live" -- more up-to-date, but perhaps not entirely consistent
with the code.

(This sounds contradictory, but isn't, the way I intend for g77
people, and any others who want to copy this structure, to use it.
For example: the current egcs trunk is for 1.2, there's a 1.1 branch,
etc.  The trunk, or "living", docs should indicate they're being
*developed* for 1.2, but might not precisely reflect the code in
the trunk.  Yet, at the same time, what those trunk docs say about
known bugs and news in 1.1.1, 1.1.2, and so on, can and should be
*the* most up-to-date, and correct, source of information.)

As a release-branch version of egcs and its docs marches forward,
the bug/news info can rapidly become focused on the pertinent
version(s).

The idea here is that we don't need to worry so much about people
pulling down unreleased versions of *branched* docs and expecting
them to be correct, but that we *do* want those docs to be correct
when releases are actually made.

(Going back to the parenthetical example above: the bugs/news info
for 1.1.2, when released, should talk only about bugs in 1.1.2, and
new for 1.1.2 and prior *releases*, which wouldn't include planned
work in the trunk, to avoid confusing people reading printed copies
of released documentation.  But, the docs, and the news and bugs
sections, would refer readers to the "living docs" at the repository and
its www site for the latest-and-greatest info on the *releases* --
which might include news and bugs items regarding 1.1.2 but discovered
*after* the 1.1.2 release -- as well as the fuzzy-state info on
upcoming releases, like 1.2.)

>  > So, I wouldn't mind adding automation to provide .html versions of
>  > those files in a suitable place.
>Hmm, maybe I mis-understood something.  I thought this is what you were
>arguing against.  

I think I just wasn't being clear enough, especially given that I
didn't know as much about what could be done (by you) vis-a-vis
.html versions of CVS docs plus the CVS branches.  Basically, I didn't
want to see bugs+news info sources being moved *out* of the
part of the repository where we already tracked releases via
branches, but didn't really understand that at the time.

>  > 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".
>Now I'm sure I mis-understood something :-)
>
>One way to approach this would be to have those markers in the texi source,
>then a page which allows the user to click on news/bugs for a particular
>release (or all releases).  That cranks up a cgi script with a suitable
>argument/environment to extract info for a particular release or all releases.

That'd be pretty cool.  In the meantime, the current approach works
pretty well for g77, especially once I implement my planned changes
to the trunk versions of the g77 docs (which should make editing
them for newly created release branches much easier).

>A nightly script to build the html files is probably the simplest scheme.  And
>it may even be sufficient for our needs, I'm not sure.

It sounds nice, but for now I like being able to check in a change,
and then immediately `lynx' over to Cygnus to see whether it worked.
I'd rather not have to wait until midnight to find out, at least
not until I have a much better understanding of the technologies
that intervene between the .texi files I edit and the `lynx' displays
(aka HTML) I see on my screen.

        tq vm, (burley)