1.1.2 bug, news lists

1.1.2 bug, news lists

[craig]

Jeff and others, before we get too closed-down on the 1.1.2 front,
could y'all make sure we'll ship it with good pointers to live
information on the web pages regarding bugs and news?

I mean, I think there have been a lot of improvements made in just
the past week or two.

But, I want us to take the time to ensure that 1.1.2 itself points
to information that we can easily keep up-to-date with regard to
newly discovered bugs (post-1.1.2-ship).

In particular, Jeff, the cgi-bin/fortrannews and cgi-bin/fortranbugs
scripts (which I can't find in my checked-out copy of wwwdocs, FWIW)
seem *nearly* ready for prime-time, and I'd like them to replace
the fortran.html stuff I recently updated by hand-tweaking the
outputs of texi2html over bugs.texi and news.texi.

So, I'm thinking there shouldn't be any equivalent to fortran.html
in the egcs-1.1.2 info on the web page -- though there should be a
link to the new bugs/news info that's automatically generated.

But, I don't know how to do that (link up stuff like that).  I could
experiment, break things, and generally annoy people, of course, but
that seems counterproductive.  :)

If you can deal with the general issues above, including replacing
the fortran.html stuff with pointers to the bug info, that'd be great.

What I'm especially interested in seeing is the top-level egcs page
contain two items:

  We try to provide late-breaking information on *known bugs*, and
  *news* about items already planned for upcoming releases.

The known-bugs link would point to that new bugs.html file, which
then would, I think, need a heading for Fortran (and some editorial
fix-ups, e.g. to the titlage), which would contain a link to your
automatically-produced fortranbugs thingy.  (Or something like that.)
Other languages might still want their news hand-coded into this
file, as they shouldn't have to also provide bugs.texi and news.texi
files like g77 has (for so long now).

As far as fixing things so fortranbugs and fortrannews properly
honor @ifhtml and @ifnothtml -- right now, fortranbugs starts off
looking pretty silly, in the middle of a sentence, apparently
due to this -- let me know if I can help.  I'm a bit of a toolsmith,
though I don't think I have the sources to things like texi2html
handy.  (E.g. if you want me to write a quicky pre-filter for it,
or something, I could do that.  Not sure which language would be
appropriate, though, and I don't know Perl yet.)

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990305184852.5825.qmail@deer >you write:
  > Jeff and others, before we get too closed-down on the 1.1.2 front,
  > could y'all make sure we'll ship it with good pointers to live
  > information on the web pages regarding bugs and news?
I don't think we should hold up a release for this, at least not this
release.  It'd be nice if we can get it in, but if we can't, then we should
move on, much like any other new feature.

If we can get it in, great.  If not we put it on the egcs-1.2 list and let it
compete for time with all the other things that need to be addressed.

  > In particular, Jeff, the cgi-bin/fortrannews and cgi-bin/fortranbugs
  > scripts (which I can't find in my checked-out copy of wwwdocs, FWIW)
  > seem *nearly* ready for prime-time, and I'd like them to replace
  > the fortran.html stuff I recently updated by hand-tweaking the
  > outputs of texi2html over bugs.texi and news.texi.
The cgi scripts aren't particularly well suited for inclusion in a
distribution since they rely on being able to grope around in the cvs 
repository.

Nor are we currently shipping our entire web site content with releases.  
Maybe we should, but that's not a change I want to make this late in the
game.  Right now we ship the install directory and the FAQ.  Before we
start adding to that I'd like to have a little better picture for how it
fits into the distributions.

[ The cgi scripts aren't in the repo because I haven't checked them -- they
  were intended to show the kinds of things we can do.  Checking them in
  is a trivial thing to do though. ]
  
  > So, I'm thinking there shouldn't be any equivalent to fortran.html
  > in the egcs-1.1.2 info on the web page -- though there should be a
  > link to the new bugs/news info that's automatically generated.
This sounds reasonable and easy.  Where precisely do you want me to link in
the cgi scripts?

And when you answer that question I suspect you'll find that you do want
a Fortran page, which has links to the bug list and news items (and possibly
the entire Fortran manual).


  > What I'm especially interested in seeing is the top-level egcs page
  > contain two items:
  > 
  >   We try to provide late-breaking information on *known bugs*, and
  >   *news* about items already planned for upcoming releases.
Again, I don't think we're really in a position to do this.  And I'd
prefer to have a little more of a clue how to tie this stuff in before we
start adding it to distributions.

Consider that the html pages we include in the distribution are meant to
be viewed locally.  Now you want to have some content remote.  Keeping these
links correct with a mixture of local and remote content isn't trivial.

Let's get the info on our web page in some manner, but not try to suck it
into the distributions yet.  That gives us time to experiment and actually
think through the distibution issues.

  > As far as fixing things so fortranbugs and fortrannews properly
  > honor @ifhtml and @ifnothtml -- right now, fortranbugs starts off
  > looking pretty silly, in the middle of a sentence, apparently
  > due to this -- let me know if I can help.  I'm a bit of a toolsmith,
  > though I don't think I have the sources to things like texi2html
  > handy.  (E.g. if you want me to write a quicky pre-filter for it,
  > or something, I could do that.  Not sure which language would be
  > appropriate, though, and I don't know Perl yet.)
Well, based on earlier conversations I think instead of farting around with
@ifhtml and friends that longer term we should have the whole manual online
in html form with links directly into the bugs and news section.

In such a scheme you'd want @ifhtml/@ifnothtml only for things which you
want to appear in the texi or html docs, but not the other.  I doubt there's
much content of this nature.
jeff

Re: 1.1.2 bug, news lists

[Joe Buck]

>   In message < 19990305184852.5825.qmail@deer >you write:
>   > Jeff and others, before we get too closed-down on the 1.1.2 front,
>   > could y'all make sure we'll ship it with good pointers to live
>   > information on the web pages regarding bugs and news?
> I don't think we should hold up a release for this, at least not this
> release.  It'd be nice if we can get it in, but if we can't, then we should
> move on, much like any other new feature.

Why not just include a text file saying how to get to the live information
on the web?

> Let's get the info on our web page in some manner, but not try to suck it
> into the distributions yet.  That gives us time to experiment and actually
> think through the distibution issues.

Right, and just say in the Fortran NEWS file where on the web to look.

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 199903052214.OAA14694@atrus.synopsys.com >you write:
  > Why not just include a text file saying how to get to the live information
  > on the web?
That would be fine.

Another approach would be to reference the bug list in the FAQ.  Which would
get the pointer into releases automatically.


  > > Let's get the info on our web page in some manner, but not try to suck it
  > > into the distributions yet.  That gives us time to experiment and actuall
  > y
  > > think through the distibution issues.
  > 
  > Right, and just say in the Fortran NEWS file where on the web to look.
Agreed.


--

Looking at the output from texi2html -menu -split_chapter seems to be our
best bet for including the entire manual online in html form.  Menus work,
the file sizes are reasonable (without the -split_chapter we got a >1M
html file for the docs... Which would take forever to download).

The next problem is figuring out how to get a pointer into the news and
bugs section.  The labels inserted by texi2html are based on section number,
not the name of the section.  I suspect with a little perl work we can add
an appropriate label that can be referenced from outside the document to
get to the bugs & news sections.

jeff

Re: 1.1.2 bug, news lists

[craig]

>  In message < 19990305184852.5825.qmail@deer >you write:
>  > Jeff and others, before we get too closed-down on the 1.1.2 front,
>  > could y'all make sure we'll ship it with good pointers to live
>  > information on the web pages regarding bugs and news?
>I don't think we should hold up a release for this, at least not this
>release.  It'd be nice if we can get it in, but if we can't, then we should
>move on, much like any other new feature.

Okay, agreed.

>  > In particular, Jeff, the cgi-bin/fortrannews and cgi-bin/fortranbugs
>  > scripts (which I can't find in my checked-out copy of wwwdocs, FWIW)
>  > seem *nearly* ready for prime-time, and I'd like them to replace
>  > the fortran.html stuff I recently updated by hand-tweaking the
>  > outputs of texi2html over bugs.texi and news.texi.
>The cgi scripts aren't particularly well suited for inclusion in a
>distribution since they rely on being able to grope around in the cvs 
>repository.

I wasn't suggesting putting them in the *distribution* -- rather,
that we make sure the distribution contains useful *pointers*,
which it might already.  1.1.2 would be great, 1.2 should definitely
be addressed.

>Nor are we currently shipping our entire web site content with releases.  

Hey, I think we should remove things like texinfo and derived files
output by gperf and lex and such -- I'm not about to suggest shipping
the entire web site, or any part of it, with a distribution!!  :)

>[ The cgi scripts aren't in the repo because I haven't checked them -- they
>  were intended to show the kinds of things we can do.  Checking them in
>  is a trivial thing to do though. ]

Okay.

>  > So, I'm thinking there shouldn't be any equivalent to fortran.html
>  > in the egcs-1.1.2 info on the web page -- though there should be a
>  > link to the new bugs/news info that's automatically generated.
>This sounds reasonable and easy.  Where precisely do you want me to link in
>the cgi scripts?

I'm not sure.  But, I think they should probably be reached via "Fortran
News" and "Fortran Bugs" links from "News" and "Bugs" pages, which
are reachable in turn from the egcs home page.  I don't exactly have
a lot of experience surfing the web to know what others do, though.

It's probably sufficient to have the distribution point to the web
site (home page) itself, if we agree to have to that home page clearly
identify links to the news and known-bugs info.

>And when you answer that question I suspect you'll find that you do want
>a Fortran page, which has links to the bug list and news items (and possibly
>the entire Fortran manual).

Oh, yes, I'm pretty sure a Fortran page makes sense, just not the
current (or previous) fortran.html file that is almost entirely
obviated by your cgi-bin scripts!  That is, I think you and Dave Love
(?) and whoever else is right that we should lean towards using
automated solutions over relying on hand-editing stuff as I've
done (via a semi-automated process).

So I feel the Fortran page should have pointers to your scripts,
and other stuff that is *not* easily automated (derived from
g77's news.texi and bugs.texi files).  Whatever that other stuff
might be, I'm not worrying about right now.

And/or, the home page should have "Known Bugs" and "Release News"
pointers to pages that, in turn, include pointers to the fortranbugs
and fortrannews thingies.

>  > What I'm especially interested in seeing is the top-level egcs page
>  > contain two items:
>  > 
>  >   We try to provide late-breaking information on *known bugs*, and
>  >   *news* about items already planned for upcoming releases.
>Again, I don't think we're really in a position to do this.  And I'd
>prefer to have a little more of a clue how to tie this stuff in before we
>start adding it to distributions.

*Not* distributions.  Well, if we decide to put it on the web page,
perhaps distributions can point to < http://egcs.cygnus.com/known-bugs >
and < http://egcs.cygnus.com/release-news >, or some such things, in
specific cases like g77's bugs.texi and news.texi files.

That way, the distributions contain documentation of known bugs and
release news as of the releases of those distributions, but also
contain prominent pointers to "live" information on the web.

>Consider that the html pages we include in the distribution are meant to
>be viewed locally.  Now you want to have some content remote.  Keeping these
>links correct with a mixture of local and remote content isn't trivial.

That's why I asked y'all to think about this, because I don't know what
all the issues are.  I don't even see why we ship HTML pages with the
distribution, unless they're truly source files (i.e. not derived from
other files)...and even then I'd wonder why they are in HTML and not
something higher-level, like texinfo (or, for that matter, plain-text).
But I haven't kept track of the pertinent discussions very well, so
there might be good answers to these opinions -- I don't really need
to know them now, so don't feel you have to rebut my opinions here.
(I.e. I know I still have a lot to learn.)

>Well, based on earlier conversations I think instead of farting around with
>@ifhtml and friends that longer term we should have the whole manual online
>in html form with links directly into the bugs and news section.

Ah, that would be pretty nice.  But we'd still need @ifhtml and friends
to be supported by texi2html, if we want one *source* for the relevant
docs, right?

>In such a scheme you'd want @ifhtml/@ifnothtml only for things which you
>want to appear in the texi or html docs, but not the other.  I doubt there's
>much content of this nature.

Hmm, you might be right.  So far I'm just using it to kludge around
the different contexts due to having snippets of the docs, instead
of the full g77 docs, made available via HTML, I guess.

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[craig]

>Another approach would be to reference the bug list in the FAQ.  Which would
>get the pointer into releases automatically.

Hmm, I haven't looked at the FAQ stuff carefully.  But that sounds
like a useful thing to have as well as other things we've discussed.
(E.g. a question like "Where can I find the latest information on known
bugs in [egcs;gcc;g77;g++;etc.]?", and another like "Where can I find
the latest news on what's in recent and upcoming releases?", could
be answered via URLs.)

>The next problem is figuring out how to get a pointer into the news and
>bugs section.  The labels inserted by texi2html are based on section number,
>not the name of the section.  I suspect with a little perl work we can add
>an appropriate label that can be referenced from outside the document to
>get to the bugs & news sections.

Dave Love has, in the past, talked about improvements to texi2html
being important somehow.  Sure wish I'd had more time and resources
to pay attention to his concerns *last* year, especially now that I
can more clearly see what he was talking about!

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[craig]

>Why not just include a text file saying how to get to the live information
>on the web?

Exactly, that's what I'd like to see, ideally in 1.1.2.  I think
just pointing to < http://egcs.cygnus.com > in g77's docs would
be sufficient for that.  Certainly that, or even more-specific
pointers, should be in 1.2.

>> Let's get the info on our web page in some manner, but not try to suck it
>> into the distributions yet.  That gives us time to experiment and actually
>> think through the distibution issues.
>
>Right, and just say in the Fortran NEWS file where on the web to look.

Yup.  Sounds good to me!

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990306044013.7118.qmail@deer >you write:
  > I wasn't suggesting putting them in the *distribution* -- rather,
  > that we make sure the distribution contains useful *pointers*,
  > which it might already.  1.1.2 would be great, 1.2 should definitely
  > be addressed.
Well, there's *lots* of things we would like to address for egcs-1.2.  No doubt
some of them will not get addressed, so we need to set priorities.  That'll
be the first order of business in the egcs-1.2 release process -- to determine
what we must have, what we'd like to have and what we can actually do in a
reasonable timeframe.


  > Hey, I think we should remove things like texinfo and derived files
  > output by gperf and lex and such -- I'm not about to suggest shipping
  > the entire web site, or any part of it, with a distribution!!  :)
Ok.  So, then you have to think about precisely how to get the information
from one location to another.  This can be nontrivial -- witness the problems
with links and the physical location of things like faq.html and FAQ.

This issue may argue that we should have a separate directory for all the
generated HTML files with the same basic skeleton structure as the web
site.  That would significantly simplify these problems.

  > >  were intended to show the kinds of things we can do.  Checking them in
  > >  is a trivial thing to do though. ]
  > 
  > Okay.
After last night/today's hacking, I think the cgi scripts should go away ;-)  

What I've got now is a shell script (which we'll probably right nightly) that
extracts various .texi files out of the repository, and converts them into
html and installs them onto the web server.

The shell script also determines the name of the g77 news and bugs html files
(since they can change as the g77 manual changes) and creates a suitable
symlink on the server so that we can always find those two sections via
a well-known name.

The nice thing is, it's a complete manual.  So from within the news section,
I can go up to the toplevel table of contents for the g77 manual,
forward/backward, etc.

See:

http://egcs.cygnus.com/onlinedocs/index.html






  > I'm not sure.  But, I think they should probably be reached via "Fortran
  > News" and "Fortran Bugs" links from "News" and "Bugs" pages, which
  > are reachable in turn from the egcs home page.  I don't exactly have
  > a lot of experience surfing the web to know what others do, though.
Well, this highlights one of the long term issues we need to address -- we're
merging multiple projects, with multiple news files, bug lists, etc.

Long term, do we have a single news section, or do we continue to have
each language do its own news section (with a pointer from the generic
news to language specific news)?  Similarly for bug lists.


  > It's probably sufficient to have the distribution point to the web
  > site (home page) itself, if we agree to have to that home page clearly
  > identify links to the news and known-bugs info.
I'll note that the bugs page doesn't appear on the toplevel page, but only
on the release pages.

  > *Not* distributions.  Well, if we decide to put it on the web page,
  > perhaps distributions can point to < http://egcs.cygnus.com/known-bugs >
  > and < http://egcs.cygnus.com/release-news >, or some such things, in
  > specific cases like g77's bugs.texi and news.texi files.
Typically release specific news has gone onto a page specific for that
release.  Not ideal and I doubt I have time to revamp all of that right
now. 


  > That's why I asked y'all to think about this, because I don't know what
  > all the issues are.  I don't even see why we ship HTML pages with the
  > distribution, unless they're truly source files (i.e. not derived from
  > other files)...and even then I'd wonder why they are in HTML and not
  > something higher-level, like texinfo (or, for that matter, plain-text).
  > But I haven't kept track of the pertinent discussions very well, so
  > there might be good answers to these opinions -- I don't really need
  > to know them now, so don't feel you have to rebut my opinions here.
  > (I.e. I know I still have a lot to learn.)
The installation documentation is only in html right now.  Which leads directly
into my desire to revamp all of the installation documentation.  We've got
install instructions for gcc, g77, libstdc++ which are 90% obsoleted by the
toplevel system install instructions.

We need to unite the installation instructions so that we have an install
guide for the project, rather than an install guide for each sub-project that
we fold in over time.

The same desire may hold true for the way we handle bugs and news.  I'm
really not sure yet.

  > Ah, that would be pretty nice.  But we'd still need @ifhtml and friends
  > to be supported by texi2html, if we want one *source* for the relevant
  > docs, right?
Why?  If the content is the same, then the @ifhtml becomes unnecessary.  And
I think we want the content to be the same.  The less hackery we have to do
to convert the docs, the better.

  > Hmm, you might be right.  So far I'm just using it to kludge around
  > the different contexts due to having snippets of the docs, instead
  > of the full g77 docs, made available via HTML, I guess.
Right.   Making the full docs available kills most/all of the need for @ifhtml.

This whole situation may come from a mis-guided mentality that users actually
care about *all* the documentation made available by the project.  That may
have been true 10 years ago, but I doubt it's true now.

ie, at one time it made sense for the install, extensions, bugs, news, and
internals documents to be one document.

Then over time we found it desirable to split off the installation guide a 
little as well as bugs & news.  IMHO, this has happened due to a shift in the
folks doing installs and end-users.  It was a soft split in that we still had
one manual, but some limited capability to extract smaller pieces of that
manual to generate INSTALL and some other files.


As the popularity of gcc continues to grow the model of one manual for
everything you'd ever want to know becomes less and less relavent.  Thus my
desire to separate manuals based on their intended audience.

I want to see (long term) a single, complete installation manual for the
entire project (target audience -- folks installing the compiler)

Then I want a manual for users -- news, bugs, language extensions, switches,
etc.

And finally a manual for developers (internal RTL format, machine macros, etc)

Each manual should be independent of the other two, particularly in how they
cross-reference each other.



jeff

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990306044434.7143.qmail@deer >you write:
  > Hmm, I haven't looked at the FAQ stuff carefully.  But that sounds
  > like a useful thing to have as well as other things we've discussed.
  > (E.g. a question like "Where can I find the latest information on known
  > bugs in [egcs;gcc;g77;g++;etc.]?", and another like "Where can I find
  > the latest news on what's in recent and upcoming releases?", could
  > be answered via URLs.)
Right.  We don't have a good bugs/news section for the main compiler or g++
at the moment.

I guess the first step would be to reference gcc/NEWS and gcc/cp/NEWS files
(there is not html equivalent for gcc or g++).


  > >The next problem is figuring out how to get a pointer into the news and
  > >bugs section.  The labels inserted by texi2html are based on section
  > >number, not the name of the section.  I suspect with a little perl work
  > >we can add an appropriate label that can be referenced from outside the
  > >document to get to the bugs & news sections.
  > 
  > Dave Love has, in the past, talked about improvements to texi2html
  > being important somehow.  Sure wish I'd had more time and resources
  > to pay attention to his concerns *last* year, especially now that I
  > can more clearly see what he was talking about!
Well, it'll be an ongoing project I'm sure.

The approach I've taken for now is to have a script look at the generated
table of contents file, find the html reference for the bugs and news section
and extract its filename.

Then it makes a symlink called "g77_news.html" to whatever file actually has
the g77 news section.  Simlarly for the bugs section.

That way we can always get to the news via "g77_news.html" and "g77_bugs.html".

Not pretty, but functional.  It may be the case that with some magic tags in
the texi source that we could do the same automatically.  I don't really know
enough about texi or texi2html to know if that's possible.

jeff

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990306044124.7129.qmail@deer >you write:
  > >Why not just include a text file saying how to get to the live information
  > >on the web?
  > 
  > Exactly, that's what I'd like to see, ideally in 1.1.2.  I think
  > just pointing to < http://egcs.cygnus.com > in g77's docs would
  > be sufficient for that.  Certainly that, or even more-specific
  > pointers, should be in 1.2.
OK.  We already have a "bugs.html" file in the toplevel of our web page.  About
a week or two ago it was made less C++ specific (thanks whomever did that).

I've tweaked it to reference the bugs section in the g77 manual.  Which works
fine for the online version, but not well in the release itself since we don't
have those html-ized files immediately available.

The FAQ does reference the bugs file from the most obvious place.

If you want to put a reference in the g77 documentation to the bugs and news
file use:

http://egcs.cygnus.com/onlinedocs/g77_bugs.html
http://egcs.cygnus.com/onlinedocs/g77_news.html

And if you want to reference the manual as a whole:
http://egcs.cygnus.com/onlinedocs/g77_toc.html

jeff

Re: 1.1.2 bug, news lists

[Gerald Pfeifer]

On 5 Mar 1999 craig@jcb-sc.com wrote:
> Jeff and others, before we get too closed-down on the 1.1.2 front,
> could y'all make sure we'll ship it with good pointers to live
> information on the web pages regarding bugs and news?

Catching up this entire thread after the weekend and just having committed
some additional wwwdocs fixes in preparation for the release...

> I mean, I think there have been a lot of improvements made in just
> the past week or two.

Is there anything you'd still like to see in 1.1.2 resp. in general?

> What I'm especially interested in seeing is the top-level egcs page
> contain two items:
> 
>   We try to provide late-breaking information on *known bugs*, and
>   *news* about items already planned for upcoming releases.

I have just committed a patch adding a link to bugs.html to the main
page.

With regard to a "forthcoming.html", well, that depends on someone
providing such information.


And later, Jeff wrote:
> Another approach would be to reference the bug list in the FAQ.  
> Which would get the pointer into releases automatically.

We actually already have not one, but two links to bugs.html in the FAQ. ;-)


And Craig again:
> I don't even see why we ship HTML pages with the distribution, unless
> they're truly source files (i.e. not derived from other files)...and
> even then I'd wonder why they are in HTML and not something
> higher-level, like texinfo (or, for that matter, plain-text).

We also ship plain-text versions (via `lynx -dump`) of those HTML files in
the distribution.

As to why HTML, this is the format most people can cope with easily (by
means of lynx, Netscape or even vi), while very few would want to read
plain *.texi files or use GNU info, at least according to my personal 
experience.

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

Re: 1.1.2 bug, news lists

[craig]

>If you want to put a reference in the g77 documentation to the bugs and news
>file use:
>
> http://egcs.cygnus.com/onlinedocs/g77_bugs.html
> http://egcs.cygnus.com/onlinedocs/g77_news.html
>
>And if you want to reference the manual as a whole:
> http://egcs.cygnus.com/onlinedocs/g77_toc.html

Jeff, I've finally looked at these.  *Really* nice.  Two things:

  1.  g77_bugs.html grabs the entire "Known Causes Of Trouble..."
      section of the manual, which is pretty big.  I think this is
      good, at least theoretically, but...

  2.  Chasing a link, even to a node in the currently open page,
      can sometimes cause the entire page to be re-read.  (E.g.
      this happens starting with g77_bugs.html and chasing "But-Bugs"
      in the first menu.  At least for me, using lynx.)

Not sure what to suggest, except *possibly*, for the near term,
a specific link to the "Actual Bugs" section, which derives from
news.texi, might be useful...e.g. g77_actualbugs.html, in its
own menu under g77_bugs.html, if possible.

I'm planning on adding links to these resources (g77_toc.html,
g77_bugs.html, and g77_news.html) to g77's documentation for egcs 1.2
*and*, unless you say otherwise, for egcs 1.1.2.

But I won't get to it before 11pm tonite at the earliest, and perhaps
not until tomorrow or Thursday.  (This is going to be a busy week for me,
for reasons unrelated to egcs.)

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990309234749.17043.qmail@deer >you write:
  > Jeff, I've finally looked at these.  *Really* nice.  Two things:
  > 
  >   1.  g77_bugs.html grabs the entire "Known Causes Of Trouble..."
  >       section of the manual, which is pretty big.  I think this is
  >       good, at least theoretically, but...
I think it's good too :-)  And pointing into a subsection is more difficult :-)


  >   2.  Chasing a link, even to a node in the currently open page,
  >       can sometimes cause the entire page to be re-read.  (E.g.
  >       this happens starting with g77_bugs.html and chasing "But-Bugs"
  >       in the first menu.  At least for me, using lynx.)
That's because the links, which appear to you to be in the same file are
actually in different files.

ie, you started by looking at g77_news.html  When you follow a link you'll
find that you actually go into something like g77_20.html

If there's a better way to do this I'm open to suggestions.


  > I'm planning on adding links to these resources (g77_toc.html,
  > g77_bugs.html, and g77_news.html) to g77's documentation for egcs 1.2
  > *and*, unless you say otherwise, for egcs 1.1.2.
Please do.

  > But I won't get to it before 11pm tonite at the earliest, and perhaps
  > not until tomorrow or Thursday.  (This is going to be a busy week for me,
  > for reasons unrelated to egcs.)
That should be fine since I'll spin the release on Friday after updating
the version #s and the like.

Thanks,
jef

Re: 1.1.2 bug, news lists

[craig]

>  >   2.  Chasing a link, even to a node in the currently open page,
>  >       can sometimes cause the entire page to be re-read.  (E.g.
>  >       this happens starting with g77_bugs.html and chasing "But-Bugs"
>  >       in the first menu.  At least for me, using lynx.)
>That's because the links, which appear to you to be in the same file are
>actually in different files.
>
>ie, you started by looking at g77_news.html  When you follow a link you'll
>find that you actually go into something like g77_20.html

That's strange, because the information is already on my screen.  I.e.
I go to g77_bugs.html, get 94K, then follow a link to something entirely
within the same file I already have, and it reads a whole new one.

Ah, I think I see what's going on now, and your explanation fits it.
Basically, g77_news.html is a complete 94K file containing the
relevant section, but all its links to the info it contains are really
to, e.g., g77_20.html.

So, only the first time somebody follows a link, will it get re-read.
After that, they "live" in the "real" file, and can move around within
links contained therein with no re-reading.

Seems not so bad to me.

>If there's a better way to do this I'm open to suggestions.

Can't help there at this time, I know way too little about this stuff.

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990310155223.19500.qmail@deer >you write:
  > >  >   2.  Chasing a link, even to a node in the currently open page,
  > >  >       can sometimes cause the entire page to be re-read.  (E.g.
  > >  >       this happens starting with g77_bugs.html and chasing "But-Bugs"
  > >  >       in the first menu.  At least for me, using lynx.)
  > >That's because the links, which appear to you to be in the same file are
  > >actually in different files.
  > >
  > >ie, you started by looking at g77_news.html  When you follow a link you'll
  > >find that you actually go into something like g77_20.html
  > 
  > That's strange, because the information is already on my screen.  I.e.
  > I go to g77_bugs.html, get 94K, then follow a link to something entirely
  > within the same file I already have, and it reads a whole new one.
It's not the same file from the web server's standpoint.  That's the souce of
the confusion I think.

  > Ah, I think I see what's going on now, and your explanation fits it.
  > Basically, g77_news.html is a complete 94K file containing the
  > relevant section, but all its links to the info it contains are really
  > to, e.g., g77_20.html.
Very close.  g77_news.html is a symbolic link to g77_xx.html.  So, in effect
it is a different file.

  > So, only the first time somebody follows a link, will it get re-read.
  > After that, they "live" in the "real" file, and can move around within
  > links contained therein with no re-reading.
Correct.

Re: 1.1.2 bug, news lists

[craig]

>Very close.  g77_news.html is a symbolic link to g77_xx.html.  So, in effect
>it is a different file.

Right, sorry, you told me this already, and I didn't thoroughly read
the email (though I saved it for later reading).

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[craig]

>On 5 Mar 1999 craig@jcb-sc.com wrote:
>> Jeff and others, before we get too closed-down on the 1.1.2 front,
>> could y'all make sure we'll ship it with good pointers to live
>> information on the web pages regarding bugs and news?
>
>Catching up this entire thread after the weekend and just having committed
>some additional wwwdocs fixes in preparation for the release...

Yup, I want to catch up on what you've been doing, and try to
understand the resulting structure better, before suggesting (or
doing) much more.

>> I mean, I think there have been a lot of improvements made in just
>> the past week or two.
>
>Is there anything you'd still like to see in 1.1.2 resp. in general?

Aside from worrying about bug-fixes to g77?  :)

No, I think the most recent changes have the sorts of references to
the new "living docs" Jeff has added to the web site that should
suffice for some time.

>> What I'm especially interested in seeing is the top-level egcs page
>> contain two items:
>> 
>>   We try to provide late-breaking information on *known bugs*, and
>>   *news* about items already planned for upcoming releases.
>
>I have just committed a patch adding a link to bugs.html to the main
>page.

Okay, I haven't reviewed these things yet.

>With regard to a "forthcoming.html", well, that depends on someone
>providing such information.

No, what I meant was, e.g., the "g77_news.html" link (aka the "News"
node of the g77 docs) that pulls up the news info from the *trunk*
of the repository.

As long as this is kept reasonably up-to-date vis-a-vis ongoing work
on g77 (in the trunk), it amounts to "forthcoming news".

What I noticed, when Jeff first put up his cgi-bin scripts, was that
my tendency to try and keep news.texi (and bugs.texi) up-to-date,
recently pretty good, made the web pages look like they were documenting
an actual release.

So I'm planning on making some changes to clarify, to readers of
trunk-based docs, that they're reading works-in-progress docs, to a
degree moreso than the docs provided with actual releases.

And, I'm also trying to ensure that whatever we do for g77's sake
(to accommodate my tendency to document things in a rather pro-
active manner, except when I forget or get lazy ;-) can be easily
copied by maintainers of other front ends, libraries, whatever.
I'm not really sure how easy it is, though, so I'm just trying to
avoid assuming it's okay to special-case g77 in some new way(s).

>We also ship plain-text versions (via `lynx -dump`) of those HTML files in
>the distribution.

Hmm.

>As to why HTML, this is the format most people can cope with easily (by
>means of lynx, Netscape or even vi), while very few would want to read
>plain *.texi files or use GNU info, at least according to my personal 
>experience.

Hmm again.  I wonder if things would be simpler if we took all these
derived files out of the *repository*, and had them put into
distributions automatically by the distribution-making mechanism.
(There are upsides and downsides to this that I can already see.)

Oh well, it's not a pressing issue, for me right now, anyway.

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[craig]

[Getting back to this somewhat old discussion....]

>The installation documentation is only in html right now.  Which leads directly
>into my desire to revamp all of the installation documentation.  We've got
>install instructions for gcc, g77, libstdc++ which are 90% obsoleted by the
>toplevel system install instructions.

Right.  Did you notice I modified the g77install.texi sources to the
non-egcs stuff doesn't get generated for some variants?  E.g. the
Info docs produced by building an egcs release won't, I hope, end up
with the non-egcs stuff, while those produced from the mainline (always
a development snapshot) or your nightly html-producing scripts (useful
for the general g77 audience) will.  Everyone will see the notices about
subsequent material not applying to egcs, though.

>We need to unite the installation instructions so that we have an install
>guide for the project, rather than an install guide for each sub-project that
>we fold in over time.

Yup.

>The same desire may hold true for the way we handle bugs and news.  I'm
>really not sure yet.

At least a consistent infrastructure would be useful.  Something that
permits a range of maintenance from none<->overkill, with g77 being
somewhat on the "overkill" side (AFAICT), for example.

>  > Ah, that would be pretty nice.  But we'd still need @ifhtml and friends
>  > to be supported by texi2html, if we want one *source* for the relevant
>  > docs, right?
>Why?  If the content is the same, then the @ifhtml becomes unnecessary.  And
>I think we want the content to be the same.  The less hackery we have to do
>to convert the docs, the better.

Agreed.  I've removed the @ifhtml stuff, but replaced it with what I think
are more sensible tests for exclusions (e.g. the g77install.texi stuff
above).  I *think* the result is something that is both much more maintainable
(by g77 people like myself) and more pertinent to each manifestation,
or variant, of the doc set.  I'd love some feedback on that.

>This whole situation may come from a mis-guided mentality that users actually
>care about *all* the documentation made available by the project.  That may
>have been true 10 years ago, but I doubt it's true now.

I gather there are still clusters of people who like to print out
complete manuals, bind them, put them on their shelves, and, especially
pertinent for projects like this, point their managers at them and say
things like "see, this free-software stuff is *serious*, they actually
write real documentation".

But, I agree, these days, most people want what they want when they want
it, which usually means clicking on a link here now, a link there then,
and so on.

And I've gotten at least one complaint from someone who thought it was
a bug that the "USING" macro being defined (when producing g77's docs)
should *not* include installation docs!  (I punted to gcc's model, but
agreed he's got a point -- there are more users than installers
nowadays, especially given the popularity of Linux distributions like
RedHat.)

>Then over time we found it desirable to split off the installation guide a 
>little as well as bugs & news.  IMHO, this has happened due to a shift in the
>folks doing installs and end-users.  It was a soft split in that we still had
>one manual, but some limited capability to extract smaller pieces of that
>manual to generate INSTALL and some other files.

Yup.

>As the popularity of gcc continues to grow the model of one manual for
>everything you'd ever want to know becomes less and less relavent.  Thus my
>desire to separate manuals based on their intended audience.

Sounds good to me.  And, since we ship sources for everything, it's
not a Big Project for us to offers users *choice* regarding how to
put their manuals together -- not much more than agreeing on how
such choices are to be made and implemented, e.g. GNU-wide.

>I want to see (long term) a single, complete installation manual for the
>entire project (target audience -- folks installing the compiler)
>
>Then I want a manual for users -- news, bugs, language extensions, switches,
>etc.
>
>And finally a manual for developers (internal RTL format, machine macros, etc)
>
>Each manual should be independent of the other two, particularly in how they
>cross-reference each other.

I agree, and that last part's the "hard" part, perhaps requiring some
diligence in re-organizing some of the material.

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990319021904.14950.qmail@deer >you write:
  > Right.  Did you notice I modified the g77install.texi sources to the
  > non-egcs stuff doesn't get generated for some variants?  E.g. the
  > Info docs produced by building an egcs release won't, I hope, end up
  > with the non-egcs stuff, while those produced from the mainline (always
  > a development snapshot) or your nightly html-producing scripts (useful
  > for the general g77 audience) will.  Everyone will see the notices about
  > subsequent material not applying to egcs, though.
I hadn't yet.  But I hope to soon as part of the installation guide revamp
that I'd like to get into egcs-1.2.


  > At least a consistent infrastructure would be useful.  Something that
  > permits a range of maintenance from none<->overkill, with g77 being
  > somewhat on the "overkill" side (AFAICT), for example.
Yes.  This is one of those issues where we're trying to merge multiple
projects with different ideas of how to handle news, bugs, and the like.

  > I gather there are still clusters of people who like to print out
  > complete manuals, bind them, put them on their shelves, and, especially
  > pertinent for projects like this, point their managers at them and say
  > things like "see, this free-software stuff is *serious*, they actually
  > write real documentation".
Yup.  There's still some folks like this -- myself included.  They should
still have that capability, the difference is instead of N separate manuals,
they'll have M manuals.

  > Sounds good to me.  And, since we ship sources for everything, it's
  > not a Big Project for us to offers users *choice* regarding how to
  > put their manuals together -- not much more than agreeing on how
  > such choices are to be made and implemented, e.g. GNU-wide.
Right.

Jeff

Re: 1.1.2 bug, news lists

[craig]

>Why not just include a text file saying how to get to the live information
>on the web?

Exactly, that's what I'd like to see, ideally in 1.1.2.  I think
just pointing to < http://egcs.cygnus.com > in g77's docs would
be sufficient for that.  Certainly that, or even more-specific
pointers, should be in 1.2.

>> Let's get the info on our web page in some manner, but not try to suck it
>> into the distributions yet.  That gives us time to experiment and actually
>> think through the distibution issues.
>
>Right, and just say in the Fortran NEWS file where on the web to look.

Yup.  Sounds good to me!

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[craig]

>  >   2.  Chasing a link, even to a node in the currently open page,
>  >       can sometimes cause the entire page to be re-read.  (E.g.
>  >       this happens starting with g77_bugs.html and chasing "But-Bugs"
>  >       in the first menu.  At least for me, using lynx.)
>That's because the links, which appear to you to be in the same file are
>actually in different files.
>
>ie, you started by looking at g77_news.html  When you follow a link you'll
>find that you actually go into something like g77_20.html

That's strange, because the information is already on my screen.  I.e.
I go to g77_bugs.html, get 94K, then follow a link to something entirely
within the same file I already have, and it reads a whole new one.

Ah, I think I see what's going on now, and your explanation fits it.
Basically, g77_news.html is a complete 94K file containing the
relevant section, but all its links to the info it contains are really
to, e.g., g77_20.html.

So, only the first time somebody follows a link, will it get re-read.
After that, they "live" in the "real" file, and can move around within
links contained therein with no re-reading.

Seems not so bad to me.

>If there's a better way to do this I'm open to suggestions.

Can't help there at this time, I know way too little about this stuff.

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990305184852.5825.qmail@deer >you write:
  > Jeff and others, before we get too closed-down on the 1.1.2 front,
  > could y'all make sure we'll ship it with good pointers to live
  > information on the web pages regarding bugs and news?
I don't think we should hold up a release for this, at least not this
release.  It'd be nice if we can get it in, but if we can't, then we should
move on, much like any other new feature.

If we can get it in, great.  If not we put it on the egcs-1.2 list and let it
compete for time with all the other things that need to be addressed.

  > In particular, Jeff, the cgi-bin/fortrannews and cgi-bin/fortranbugs
  > scripts (which I can't find in my checked-out copy of wwwdocs, FWIW)
  > seem *nearly* ready for prime-time, and I'd like them to replace
  > the fortran.html stuff I recently updated by hand-tweaking the
  > outputs of texi2html over bugs.texi and news.texi.
The cgi scripts aren't particularly well suited for inclusion in a
distribution since they rely on being able to grope around in the cvs 
repository.

Nor are we currently shipping our entire web site content with releases.  
Maybe we should, but that's not a change I want to make this late in the
game.  Right now we ship the install directory and the FAQ.  Before we
start adding to that I'd like to have a little better picture for how it
fits into the distributions.

[ The cgi scripts aren't in the repo because I haven't checked them -- they
  were intended to show the kinds of things we can do.  Checking them in
  is a trivial thing to do though. ]
  
  > So, I'm thinking there shouldn't be any equivalent to fortran.html
  > in the egcs-1.1.2 info on the web page -- though there should be a
  > link to the new bugs/news info that's automatically generated.
This sounds reasonable and easy.  Where precisely do you want me to link in
the cgi scripts?

And when you answer that question I suspect you'll find that you do want
a Fortran page, which has links to the bug list and news items (and possibly
the entire Fortran manual).


  > What I'm especially interested in seeing is the top-level egcs page
  > contain two items:
  > 
  >   We try to provide late-breaking information on *known bugs*, and
  >   *news* about items already planned for upcoming releases.
Again, I don't think we're really in a position to do this.  And I'd
prefer to have a little more of a clue how to tie this stuff in before we
start adding it to distributions.

Consider that the html pages we include in the distribution are meant to
be viewed locally.  Now you want to have some content remote.  Keeping these
links correct with a mixture of local and remote content isn't trivial.

Let's get the info on our web page in some manner, but not try to suck it
into the distributions yet.  That gives us time to experiment and actually
think through the distibution issues.

  > As far as fixing things so fortranbugs and fortrannews properly
  > honor @ifhtml and @ifnothtml -- right now, fortranbugs starts off
  > looking pretty silly, in the middle of a sentence, apparently
  > due to this -- let me know if I can help.  I'm a bit of a toolsmith,
  > though I don't think I have the sources to things like texi2html
  > handy.  (E.g. if you want me to write a quicky pre-filter for it,
  > or something, I could do that.  Not sure which language would be
  > appropriate, though, and I don't know Perl yet.)
Well, based on earlier conversations I think instead of farting around with
@ifhtml and friends that longer term we should have the whole manual online
in html form with links directly into the bugs and news section.

In such a scheme you'd want @ifhtml/@ifnothtml only for things which you
want to appear in the texi or html docs, but not the other.  I doubt there's
much content of this nature.
jeff

Re: 1.1.2 bug, news lists

[Joe Buck]

>   In message < 19990305184852.5825.qmail@deer >you write:
>   > Jeff and others, before we get too closed-down on the 1.1.2 front,
>   > could y'all make sure we'll ship it with good pointers to live
>   > information on the web pages regarding bugs and news?
> I don't think we should hold up a release for this, at least not this
> release.  It'd be nice if we can get it in, but if we can't, then we should
> move on, much like any other new feature.

Why not just include a text file saying how to get to the live information
on the web?

> Let's get the info on our web page in some manner, but not try to suck it
> into the distributions yet.  That gives us time to experiment and actually
> think through the distibution issues.

Right, and just say in the Fortran NEWS file where on the web to look.

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990310155223.19500.qmail@deer >you write:
  > >  >   2.  Chasing a link, even to a node in the currently open page,
  > >  >       can sometimes cause the entire page to be re-read.  (E.g.
  > >  >       this happens starting with g77_bugs.html and chasing "But-Bugs"
  > >  >       in the first menu.  At least for me, using lynx.)
  > >That's because the links, which appear to you to be in the same file are
  > >actually in different files.
  > >
  > >ie, you started by looking at g77_news.html  When you follow a link you'll
  > >find that you actually go into something like g77_20.html
  > 
  > That's strange, because the information is already on my screen.  I.e.
  > I go to g77_bugs.html, get 94K, then follow a link to something entirely
  > within the same file I already have, and it reads a whole new one.
It's not the same file from the web server's standpoint.  That's the souce of
the confusion I think.

  > Ah, I think I see what's going on now, and your explanation fits it.
  > Basically, g77_news.html is a complete 94K file containing the
  > relevant section, but all its links to the info it contains are really
  > to, e.g., g77_20.html.
Very close.  g77_news.html is a symbolic link to g77_xx.html.  So, in effect
it is a different file.

  > So, only the first time somebody follows a link, will it get re-read.
  > After that, they "live" in the "real" file, and can move around within
  > links contained therein with no re-reading.
Correct.

Re: 1.1.2 bug, news lists

[Gerald Pfeifer]

On 5 Mar 1999 craig@jcb-sc.com wrote:
> Jeff and others, before we get too closed-down on the 1.1.2 front,
> could y'all make sure we'll ship it with good pointers to live
> information on the web pages regarding bugs and news?

Catching up this entire thread after the weekend and just having committed
some additional wwwdocs fixes in preparation for the release...

> I mean, I think there have been a lot of improvements made in just
> the past week or two.

Is there anything you'd still like to see in 1.1.2 resp. in general?

> What I'm especially interested in seeing is the top-level egcs page
> contain two items:
> 
>   We try to provide late-breaking information on *known bugs*, and
>   *news* about items already planned for upcoming releases.

I have just committed a patch adding a link to bugs.html to the main
page.

With regard to a "forthcoming.html", well, that depends on someone
providing such information.


And later, Jeff wrote:
> Another approach would be to reference the bug list in the FAQ.  
> Which would get the pointer into releases automatically.

We actually already have not one, but two links to bugs.html in the FAQ. ;-)


And Craig again:
> I don't even see why we ship HTML pages with the distribution, unless
> they're truly source files (i.e. not derived from other files)...and
> even then I'd wonder why they are in HTML and not something
> higher-level, like texinfo (or, for that matter, plain-text).

We also ship plain-text versions (via `lynx -dump`) of those HTML files in
the distribution.

As to why HTML, this is the format most people can cope with easily (by
means of lynx, Netscape or even vi), while very few would want to read
plain *.texi files or use GNU info, at least according to my personal 
experience.

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

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990306044434.7143.qmail@deer >you write:
  > Hmm, I haven't looked at the FAQ stuff carefully.  But that sounds
  > like a useful thing to have as well as other things we've discussed.
  > (E.g. a question like "Where can I find the latest information on known
  > bugs in [egcs;gcc;g77;g++;etc.]?", and another like "Where can I find
  > the latest news on what's in recent and upcoming releases?", could
  > be answered via URLs.)
Right.  We don't have a good bugs/news section for the main compiler or g++
at the moment.

I guess the first step would be to reference gcc/NEWS and gcc/cp/NEWS files
(there is not html equivalent for gcc or g++).


  > >The next problem is figuring out how to get a pointer into the news and
  > >bugs section.  The labels inserted by texi2html are based on section
  > >number, not the name of the section.  I suspect with a little perl work
  > >we can add an appropriate label that can be referenced from outside the
  > >document to get to the bugs & news sections.
  > 
  > Dave Love has, in the past, talked about improvements to texi2html
  > being important somehow.  Sure wish I'd had more time and resources
  > to pay attention to his concerns *last* year, especially now that I
  > can more clearly see what he was talking about!
Well, it'll be an ongoing project I'm sure.

The approach I've taken for now is to have a script look at the generated
table of contents file, find the html reference for the bugs and news section
and extract its filename.

Then it makes a symlink called "g77_news.html" to whatever file actually has
the g77 news section.  Simlarly for the bugs section.

That way we can always get to the news via "g77_news.html" and "g77_bugs.html".

Not pretty, but functional.  It may be the case that with some magic tags in
the texi source that we could do the same automatically.  I don't really know
enough about texi or texi2html to know if that's possible.

jeff

Re: 1.1.2 bug, news lists

[craig]

>Very close.  g77_news.html is a symbolic link to g77_xx.html.  So, in effect
>it is a different file.

Right, sorry, you told me this already, and I didn't thoroughly read
the email (though I saved it for later reading).

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[craig]

>If you want to put a reference in the g77 documentation to the bugs and news
>file use:
>
> http://egcs.cygnus.com/onlinedocs/g77_bugs.html
> http://egcs.cygnus.com/onlinedocs/g77_news.html
>
>And if you want to reference the manual as a whole:
> http://egcs.cygnus.com/onlinedocs/g77_toc.html

Jeff, I've finally looked at these.  *Really* nice.  Two things:

  1.  g77_bugs.html grabs the entire "Known Causes Of Trouble..."
      section of the manual, which is pretty big.  I think this is
      good, at least theoretically, but...

  2.  Chasing a link, even to a node in the currently open page,
      can sometimes cause the entire page to be re-read.  (E.g.
      this happens starting with g77_bugs.html and chasing "But-Bugs"
      in the first menu.  At least for me, using lynx.)

Not sure what to suggest, except *possibly*, for the near term,
a specific link to the "Actual Bugs" section, which derives from
news.texi, might be useful...e.g. g77_actualbugs.html, in its
own menu under g77_bugs.html, if possible.

I'm planning on adding links to these resources (g77_toc.html,
g77_bugs.html, and g77_news.html) to g77's documentation for egcs 1.2
*and*, unless you say otherwise, for egcs 1.1.2.

But I won't get to it before 11pm tonite at the earliest, and perhaps
not until tomorrow or Thursday.  (This is going to be a busy week for me,
for reasons unrelated to egcs.)

        tq vm, (burley)

1.1.2 bug, news lists

[craig]

Jeff and others, before we get too closed-down on the 1.1.2 front,
could y'all make sure we'll ship it with good pointers to live
information on the web pages regarding bugs and news?

I mean, I think there have been a lot of improvements made in just
the past week or two.

But, I want us to take the time to ensure that 1.1.2 itself points
to information that we can easily keep up-to-date with regard to
newly discovered bugs (post-1.1.2-ship).

In particular, Jeff, the cgi-bin/fortrannews and cgi-bin/fortranbugs
scripts (which I can't find in my checked-out copy of wwwdocs, FWIW)
seem *nearly* ready for prime-time, and I'd like them to replace
the fortran.html stuff I recently updated by hand-tweaking the
outputs of texi2html over bugs.texi and news.texi.

So, I'm thinking there shouldn't be any equivalent to fortran.html
in the egcs-1.1.2 info on the web page -- though there should be a
link to the new bugs/news info that's automatically generated.

But, I don't know how to do that (link up stuff like that).  I could
experiment, break things, and generally annoy people, of course, but
that seems counterproductive.  :)

If you can deal with the general issues above, including replacing
the fortran.html stuff with pointers to the bug info, that'd be great.

What I'm especially interested in seeing is the top-level egcs page
contain two items:

  We try to provide late-breaking information on *known bugs*, and
  *news* about items already planned for upcoming releases.

The known-bugs link would point to that new bugs.html file, which
then would, I think, need a heading for Fortran (and some editorial
fix-ups, e.g. to the titlage), which would contain a link to your
automatically-produced fortranbugs thingy.  (Or something like that.)
Other languages might still want their news hand-coded into this
file, as they shouldn't have to also provide bugs.texi and news.texi
files like g77 has (for so long now).

As far as fixing things so fortranbugs and fortrannews properly
honor @ifhtml and @ifnothtml -- right now, fortranbugs starts off
looking pretty silly, in the middle of a sentence, apparently
due to this -- let me know if I can help.  I'm a bit of a toolsmith,
though I don't think I have the sources to things like texi2html
handy.  (E.g. if you want me to write a quicky pre-filter for it,
or something, I could do that.  Not sure which language would be
appropriate, though, and I don't know Perl yet.)

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[craig]

>  In message < 19990305184852.5825.qmail@deer >you write:
>  > Jeff and others, before we get too closed-down on the 1.1.2 front,
>  > could y'all make sure we'll ship it with good pointers to live
>  > information on the web pages regarding bugs and news?
>I don't think we should hold up a release for this, at least not this
>release.  It'd be nice if we can get it in, but if we can't, then we should
>move on, much like any other new feature.

Okay, agreed.

>  > In particular, Jeff, the cgi-bin/fortrannews and cgi-bin/fortranbugs
>  > scripts (which I can't find in my checked-out copy of wwwdocs, FWIW)
>  > seem *nearly* ready for prime-time, and I'd like them to replace
>  > the fortran.html stuff I recently updated by hand-tweaking the
>  > outputs of texi2html over bugs.texi and news.texi.
>The cgi scripts aren't particularly well suited for inclusion in a
>distribution since they rely on being able to grope around in the cvs 
>repository.

I wasn't suggesting putting them in the *distribution* -- rather,
that we make sure the distribution contains useful *pointers*,
which it might already.  1.1.2 would be great, 1.2 should definitely
be addressed.

>Nor are we currently shipping our entire web site content with releases.  

Hey, I think we should remove things like texinfo and derived files
output by gperf and lex and such -- I'm not about to suggest shipping
the entire web site, or any part of it, with a distribution!!  :)

>[ The cgi scripts aren't in the repo because I haven't checked them -- they
>  were intended to show the kinds of things we can do.  Checking them in
>  is a trivial thing to do though. ]

Okay.

>  > So, I'm thinking there shouldn't be any equivalent to fortran.html
>  > in the egcs-1.1.2 info on the web page -- though there should be a
>  > link to the new bugs/news info that's automatically generated.
>This sounds reasonable and easy.  Where precisely do you want me to link in
>the cgi scripts?

I'm not sure.  But, I think they should probably be reached via "Fortran
News" and "Fortran Bugs" links from "News" and "Bugs" pages, which
are reachable in turn from the egcs home page.  I don't exactly have
a lot of experience surfing the web to know what others do, though.

It's probably sufficient to have the distribution point to the web
site (home page) itself, if we agree to have to that home page clearly
identify links to the news and known-bugs info.

>And when you answer that question I suspect you'll find that you do want
>a Fortran page, which has links to the bug list and news items (and possibly
>the entire Fortran manual).

Oh, yes, I'm pretty sure a Fortran page makes sense, just not the
current (or previous) fortran.html file that is almost entirely
obviated by your cgi-bin scripts!  That is, I think you and Dave Love
(?) and whoever else is right that we should lean towards using
automated solutions over relying on hand-editing stuff as I've
done (via a semi-automated process).

So I feel the Fortran page should have pointers to your scripts,
and other stuff that is *not* easily automated (derived from
g77's news.texi and bugs.texi files).  Whatever that other stuff
might be, I'm not worrying about right now.

And/or, the home page should have "Known Bugs" and "Release News"
pointers to pages that, in turn, include pointers to the fortranbugs
and fortrannews thingies.

>  > What I'm especially interested in seeing is the top-level egcs page
>  > contain two items:
>  > 
>  >   We try to provide late-breaking information on *known bugs*, and
>  >   *news* about items already planned for upcoming releases.
>Again, I don't think we're really in a position to do this.  And I'd
>prefer to have a little more of a clue how to tie this stuff in before we
>start adding it to distributions.

*Not* distributions.  Well, if we decide to put it on the web page,
perhaps distributions can point to < http://egcs.cygnus.com/known-bugs >
and < http://egcs.cygnus.com/release-news >, or some such things, in
specific cases like g77's bugs.texi and news.texi files.

That way, the distributions contain documentation of known bugs and
release news as of the releases of those distributions, but also
contain prominent pointers to "live" information on the web.

>Consider that the html pages we include in the distribution are meant to
>be viewed locally.  Now you want to have some content remote.  Keeping these
>links correct with a mixture of local and remote content isn't trivial.

That's why I asked y'all to think about this, because I don't know what
all the issues are.  I don't even see why we ship HTML pages with the
distribution, unless they're truly source files (i.e. not derived from
other files)...and even then I'd wonder why they are in HTML and not
something higher-level, like texinfo (or, for that matter, plain-text).
But I haven't kept track of the pertinent discussions very well, so
there might be good answers to these opinions -- I don't really need
to know them now, so don't feel you have to rebut my opinions here.
(I.e. I know I still have a lot to learn.)

>Well, based on earlier conversations I think instead of farting around with
>@ifhtml and friends that longer term we should have the whole manual online
>in html form with links directly into the bugs and news section.

Ah, that would be pretty nice.  But we'd still need @ifhtml and friends
to be supported by texi2html, if we want one *source* for the relevant
docs, right?

>In such a scheme you'd want @ifhtml/@ifnothtml only for things which you
>want to appear in the texi or html docs, but not the other.  I doubt there's
>much content of this nature.

Hmm, you might be right.  So far I'm just using it to kludge around
the different contexts due to having snippets of the docs, instead
of the full g77 docs, made available via HTML, I guess.

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 199903052214.OAA14694@atrus.synopsys.com >you write:
  > Why not just include a text file saying how to get to the live information
  > on the web?
That would be fine.

Another approach would be to reference the bug list in the FAQ.  Which would
get the pointer into releases automatically.


  > > Let's get the info on our web page in some manner, but not try to suck it
  > > into the distributions yet.  That gives us time to experiment and actuall
  > y
  > > think through the distibution issues.
  > 
  > Right, and just say in the Fortran NEWS file where on the web to look.
Agreed.


--

Looking at the output from texi2html -menu -split_chapter seems to be our
best bet for including the entire manual online in html form.  Menus work,
the file sizes are reasonable (without the -split_chapter we got a >1M
html file for the docs... Which would take forever to download).

The next problem is figuring out how to get a pointer into the news and
bugs section.  The labels inserted by texi2html are based on section number,
not the name of the section.  I suspect with a little perl work we can add
an appropriate label that can be referenced from outside the document to
get to the bugs & news sections.

jeff

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990306044013.7118.qmail@deer >you write:
  > I wasn't suggesting putting them in the *distribution* -- rather,
  > that we make sure the distribution contains useful *pointers*,
  > which it might already.  1.1.2 would be great, 1.2 should definitely
  > be addressed.
Well, there's *lots* of things we would like to address for egcs-1.2.  No doubt
some of them will not get addressed, so we need to set priorities.  That'll
be the first order of business in the egcs-1.2 release process -- to determine
what we must have, what we'd like to have and what we can actually do in a
reasonable timeframe.


  > Hey, I think we should remove things like texinfo and derived files
  > output by gperf and lex and such -- I'm not about to suggest shipping
  > the entire web site, or any part of it, with a distribution!!  :)
Ok.  So, then you have to think about precisely how to get the information
from one location to another.  This can be nontrivial -- witness the problems
with links and the physical location of things like faq.html and FAQ.

This issue may argue that we should have a separate directory for all the
generated HTML files with the same basic skeleton structure as the web
site.  That would significantly simplify these problems.

  > >  were intended to show the kinds of things we can do.  Checking them in
  > >  is a trivial thing to do though. ]
  > 
  > Okay.
After last night/today's hacking, I think the cgi scripts should go away ;-)  

What I've got now is a shell script (which we'll probably right nightly) that
extracts various .texi files out of the repository, and converts them into
html and installs them onto the web server.

The shell script also determines the name of the g77 news and bugs html files
(since they can change as the g77 manual changes) and creates a suitable
symlink on the server so that we can always find those two sections via
a well-known name.

The nice thing is, it's a complete manual.  So from within the news section,
I can go up to the toplevel table of contents for the g77 manual,
forward/backward, etc.

See:

http://egcs.cygnus.com/onlinedocs/index.html






  > I'm not sure.  But, I think they should probably be reached via "Fortran
  > News" and "Fortran Bugs" links from "News" and "Bugs" pages, which
  > are reachable in turn from the egcs home page.  I don't exactly have
  > a lot of experience surfing the web to know what others do, though.
Well, this highlights one of the long term issues we need to address -- we're
merging multiple projects, with multiple news files, bug lists, etc.

Long term, do we have a single news section, or do we continue to have
each language do its own news section (with a pointer from the generic
news to language specific news)?  Similarly for bug lists.


  > It's probably sufficient to have the distribution point to the web
  > site (home page) itself, if we agree to have to that home page clearly
  > identify links to the news and known-bugs info.
I'll note that the bugs page doesn't appear on the toplevel page, but only
on the release pages.

  > *Not* distributions.  Well, if we decide to put it on the web page,
  > perhaps distributions can point to < http://egcs.cygnus.com/known-bugs >
  > and < http://egcs.cygnus.com/release-news >, or some such things, in
  > specific cases like g77's bugs.texi and news.texi files.
Typically release specific news has gone onto a page specific for that
release.  Not ideal and I doubt I have time to revamp all of that right
now. 


  > That's why I asked y'all to think about this, because I don't know what
  > all the issues are.  I don't even see why we ship HTML pages with the
  > distribution, unless they're truly source files (i.e. not derived from
  > other files)...and even then I'd wonder why they are in HTML and not
  > something higher-level, like texinfo (or, for that matter, plain-text).
  > But I haven't kept track of the pertinent discussions very well, so
  > there might be good answers to these opinions -- I don't really need
  > to know them now, so don't feel you have to rebut my opinions here.
  > (I.e. I know I still have a lot to learn.)
The installation documentation is only in html right now.  Which leads directly
into my desire to revamp all of the installation documentation.  We've got
install instructions for gcc, g77, libstdc++ which are 90% obsoleted by the
toplevel system install instructions.

We need to unite the installation instructions so that we have an install
guide for the project, rather than an install guide for each sub-project that
we fold in over time.

The same desire may hold true for the way we handle bugs and news.  I'm
really not sure yet.

  > Ah, that would be pretty nice.  But we'd still need @ifhtml and friends
  > to be supported by texi2html, if we want one *source* for the relevant
  > docs, right?
Why?  If the content is the same, then the @ifhtml becomes unnecessary.  And
I think we want the content to be the same.  The less hackery we have to do
to convert the docs, the better.

  > Hmm, you might be right.  So far I'm just using it to kludge around
  > the different contexts due to having snippets of the docs, instead
  > of the full g77 docs, made available via HTML, I guess.
Right.   Making the full docs available kills most/all of the need for @ifhtml.

This whole situation may come from a mis-guided mentality that users actually
care about *all* the documentation made available by the project.  That may
have been true 10 years ago, but I doubt it's true now.

ie, at one time it made sense for the install, extensions, bugs, news, and
internals documents to be one document.

Then over time we found it desirable to split off the installation guide a 
little as well as bugs & news.  IMHO, this has happened due to a shift in the
folks doing installs and end-users.  It was a soft split in that we still had
one manual, but some limited capability to extract smaller pieces of that
manual to generate INSTALL and some other files.


As the popularity of gcc continues to grow the model of one manual for
everything you'd ever want to know becomes less and less relavent.  Thus my
desire to separate manuals based on their intended audience.

I want to see (long term) a single, complete installation manual for the
entire project (target audience -- folks installing the compiler)

Then I want a manual for users -- news, bugs, language extensions, switches,
etc.

And finally a manual for developers (internal RTL format, machine macros, etc)

Each manual should be independent of the other two, particularly in how they
cross-reference each other.



jeff

Re: 1.1.2 bug, news lists

[craig]

>Another approach would be to reference the bug list in the FAQ.  Which would
>get the pointer into releases automatically.

Hmm, I haven't looked at the FAQ stuff carefully.  But that sounds
like a useful thing to have as well as other things we've discussed.
(E.g. a question like "Where can I find the latest information on known
bugs in [egcs;gcc;g77;g++;etc.]?", and another like "Where can I find
the latest news on what's in recent and upcoming releases?", could
be answered via URLs.)

>The next problem is figuring out how to get a pointer into the news and
>bugs section.  The labels inserted by texi2html are based on section number,
>not the name of the section.  I suspect with a little perl work we can add
>an appropriate label that can be referenced from outside the document to
>get to the bugs & news sections.

Dave Love has, in the past, talked about improvements to texi2html
being important somehow.  Sure wish I'd had more time and resources
to pay attention to his concerns *last* year, especially now that I
can more clearly see what he was talking about!

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[craig]

[Getting back to this somewhat old discussion....]

>The installation documentation is only in html right now.  Which leads directly
>into my desire to revamp all of the installation documentation.  We've got
>install instructions for gcc, g77, libstdc++ which are 90% obsoleted by the
>toplevel system install instructions.

Right.  Did you notice I modified the g77install.texi sources to the
non-egcs stuff doesn't get generated for some variants?  E.g. the
Info docs produced by building an egcs release won't, I hope, end up
with the non-egcs stuff, while those produced from the mainline (always
a development snapshot) or your nightly html-producing scripts (useful
for the general g77 audience) will.  Everyone will see the notices about
subsequent material not applying to egcs, though.

>We need to unite the installation instructions so that we have an install
>guide for the project, rather than an install guide for each sub-project that
>we fold in over time.

Yup.

>The same desire may hold true for the way we handle bugs and news.  I'm
>really not sure yet.

At least a consistent infrastructure would be useful.  Something that
permits a range of maintenance from none<->overkill, with g77 being
somewhat on the "overkill" side (AFAICT), for example.

>  > Ah, that would be pretty nice.  But we'd still need @ifhtml and friends
>  > to be supported by texi2html, if we want one *source* for the relevant
>  > docs, right?
>Why?  If the content is the same, then the @ifhtml becomes unnecessary.  And
>I think we want the content to be the same.  The less hackery we have to do
>to convert the docs, the better.

Agreed.  I've removed the @ifhtml stuff, but replaced it with what I think
are more sensible tests for exclusions (e.g. the g77install.texi stuff
above).  I *think* the result is something that is both much more maintainable
(by g77 people like myself) and more pertinent to each manifestation,
or variant, of the doc set.  I'd love some feedback on that.

>This whole situation may come from a mis-guided mentality that users actually
>care about *all* the documentation made available by the project.  That may
>have been true 10 years ago, but I doubt it's true now.

I gather there are still clusters of people who like to print out
complete manuals, bind them, put them on their shelves, and, especially
pertinent for projects like this, point their managers at them and say
things like "see, this free-software stuff is *serious*, they actually
write real documentation".

But, I agree, these days, most people want what they want when they want
it, which usually means clicking on a link here now, a link there then,
and so on.

And I've gotten at least one complaint from someone who thought it was
a bug that the "USING" macro being defined (when producing g77's docs)
should *not* include installation docs!  (I punted to gcc's model, but
agreed he's got a point -- there are more users than installers
nowadays, especially given the popularity of Linux distributions like
RedHat.)

>Then over time we found it desirable to split off the installation guide a 
>little as well as bugs & news.  IMHO, this has happened due to a shift in the
>folks doing installs and end-users.  It was a soft split in that we still had
>one manual, but some limited capability to extract smaller pieces of that
>manual to generate INSTALL and some other files.

Yup.

>As the popularity of gcc continues to grow the model of one manual for
>everything you'd ever want to know becomes less and less relavent.  Thus my
>desire to separate manuals based on their intended audience.

Sounds good to me.  And, since we ship sources for everything, it's
not a Big Project for us to offers users *choice* regarding how to
put their manuals together -- not much more than agreeing on how
such choices are to be made and implemented, e.g. GNU-wide.

>I want to see (long term) a single, complete installation manual for the
>entire project (target audience -- folks installing the compiler)
>
>Then I want a manual for users -- news, bugs, language extensions, switches,
>etc.
>
>And finally a manual for developers (internal RTL format, machine macros, etc)
>
>Each manual should be independent of the other two, particularly in how they
>cross-reference each other.

I agree, and that last part's the "hard" part, perhaps requiring some
diligence in re-organizing some of the material.

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990306044124.7129.qmail@deer >you write:
  > >Why not just include a text file saying how to get to the live information
  > >on the web?
  > 
  > Exactly, that's what I'd like to see, ideally in 1.1.2.  I think
  > just pointing to < http://egcs.cygnus.com > in g77's docs would
  > be sufficient for that.  Certainly that, or even more-specific
  > pointers, should be in 1.2.
OK.  We already have a "bugs.html" file in the toplevel of our web page.  About
a week or two ago it was made less C++ specific (thanks whomever did that).

I've tweaked it to reference the bugs section in the g77 manual.  Which works
fine for the online version, but not well in the release itself since we don't
have those html-ized files immediately available.

The FAQ does reference the bugs file from the most obvious place.

If you want to put a reference in the g77 documentation to the bugs and news
file use:

http://egcs.cygnus.com/onlinedocs/g77_bugs.html
http://egcs.cygnus.com/onlinedocs/g77_news.html

And if you want to reference the manual as a whole:
http://egcs.cygnus.com/onlinedocs/g77_toc.html

jeff

Re: 1.1.2 bug, news lists

[craig]

>On 5 Mar 1999 craig@jcb-sc.com wrote:
>> Jeff and others, before we get too closed-down on the 1.1.2 front,
>> could y'all make sure we'll ship it with good pointers to live
>> information on the web pages regarding bugs and news?
>
>Catching up this entire thread after the weekend and just having committed
>some additional wwwdocs fixes in preparation for the release...

Yup, I want to catch up on what you've been doing, and try to
understand the resulting structure better, before suggesting (or
doing) much more.

>> I mean, I think there have been a lot of improvements made in just
>> the past week or two.
>
>Is there anything you'd still like to see in 1.1.2 resp. in general?

Aside from worrying about bug-fixes to g77?  :)

No, I think the most recent changes have the sorts of references to
the new "living docs" Jeff has added to the web site that should
suffice for some time.

>> What I'm especially interested in seeing is the top-level egcs page
>> contain two items:
>> 
>>   We try to provide late-breaking information on *known bugs*, and
>>   *news* about items already planned for upcoming releases.
>
>I have just committed a patch adding a link to bugs.html to the main
>page.

Okay, I haven't reviewed these things yet.

>With regard to a "forthcoming.html", well, that depends on someone
>providing such information.

No, what I meant was, e.g., the "g77_news.html" link (aka the "News"
node of the g77 docs) that pulls up the news info from the *trunk*
of the repository.

As long as this is kept reasonably up-to-date vis-a-vis ongoing work
on g77 (in the trunk), it amounts to "forthcoming news".

What I noticed, when Jeff first put up his cgi-bin scripts, was that
my tendency to try and keep news.texi (and bugs.texi) up-to-date,
recently pretty good, made the web pages look like they were documenting
an actual release.

So I'm planning on making some changes to clarify, to readers of
trunk-based docs, that they're reading works-in-progress docs, to a
degree moreso than the docs provided with actual releases.

And, I'm also trying to ensure that whatever we do for g77's sake
(to accommodate my tendency to document things in a rather pro-
active manner, except when I forget or get lazy ;-) can be easily
copied by maintainers of other front ends, libraries, whatever.
I'm not really sure how easy it is, though, so I'm just trying to
avoid assuming it's okay to special-case g77 in some new way(s).

>We also ship plain-text versions (via `lynx -dump`) of those HTML files in
>the distribution.

Hmm.

>As to why HTML, this is the format most people can cope with easily (by
>means of lynx, Netscape or even vi), while very few would want to read
>plain *.texi files or use GNU info, at least according to my personal 
>experience.

Hmm again.  I wonder if things would be simpler if we took all these
derived files out of the *repository*, and had them put into
distributions automatically by the distribution-making mechanism.
(There are upsides and downsides to this that I can already see.)

Oh well, it's not a pressing issue, for me right now, anyway.

        tq vm, (burley)

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990309234749.17043.qmail@deer >you write:
  > Jeff, I've finally looked at these.  *Really* nice.  Two things:
  > 
  >   1.  g77_bugs.html grabs the entire "Known Causes Of Trouble..."
  >       section of the manual, which is pretty big.  I think this is
  >       good, at least theoretically, but...
I think it's good too :-)  And pointing into a subsection is more difficult :-)


  >   2.  Chasing a link, even to a node in the currently open page,
  >       can sometimes cause the entire page to be re-read.  (E.g.
  >       this happens starting with g77_bugs.html and chasing "But-Bugs"
  >       in the first menu.  At least for me, using lynx.)
That's because the links, which appear to you to be in the same file are
actually in different files.

ie, you started by looking at g77_news.html  When you follow a link you'll
find that you actually go into something like g77_20.html

If there's a better way to do this I'm open to suggestions.


  > I'm planning on adding links to these resources (g77_toc.html,
  > g77_bugs.html, and g77_news.html) to g77's documentation for egcs 1.2
  > *and*, unless you say otherwise, for egcs 1.1.2.
Please do.

  > But I won't get to it before 11pm tonite at the earliest, and perhaps
  > not until tomorrow or Thursday.  (This is going to be a busy week for me,
  > for reasons unrelated to egcs.)
That should be fine since I'll spin the release on Friday after updating
the version #s and the like.

Thanks,
jef

Re: 1.1.2 bug, news lists

[Jeffrey A Law]

  In message < 19990319021904.14950.qmail@deer >you write:
  > Right.  Did you notice I modified the g77install.texi sources to the
  > non-egcs stuff doesn't get generated for some variants?  E.g. the
  > Info docs produced by building an egcs release won't, I hope, end up
  > with the non-egcs stuff, while those produced from the mainline (always
  > a development snapshot) or your nightly html-producing scripts (useful
  > for the general g77 audience) will.  Everyone will see the notices about
  > subsequent material not applying to egcs, though.
I hadn't yet.  But I hope to soon as part of the installation guide revamp
that I'd like to get into egcs-1.2.


  > At least a consistent infrastructure would be useful.  Something that
  > permits a range of maintenance from none<->overkill, with g77 being
  > somewhat on the "overkill" side (AFAICT), for example.
Yes.  This is one of those issues where we're trying to merge multiple
projects with different ideas of how to handle news, bugs, and the like.

  > I gather there are still clusters of people who like to print out
  > complete manuals, bind them, put them on their shelves, and, especially
  > pertinent for projects like this, point their managers at them and say
  > things like "see, this free-software stuff is *serious*, they actually
  > write real documentation".
Yup.  There's still some folks like this -- myself included.  They should
still have that capability, the difference is instead of N separate manuals,
they'll have M manuals.

  > Sounds good to me.  And, since we ship sources for everything, it's
  > not a Big Project for us to offers users *choice* regarding how to
  > put their manuals together -- not much more than agreeing on how
  > such choices are to be made and implemented, e.g. GNU-wide.
Right.

Jeff