Re: 1.1.2 bug, news lists

[Jeffrey A Law <law at hurl dot cygnus dot com>]

  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