This is the mail archive of the egcs@egcs.cygnus.com mailing list for the EGCS project. See the EGCS home page for more information.
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