This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: 1.1.2 bug, news lists


[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)


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]