This is the mail archive of the libstdc++@sources.redhat.com mailing list for the libstdc++ project.


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

splitting up docs dir (was Re: Doxygen - another sample, preliminary comments)


On Sun, Nov 26, 2000 at 10:26:01PM -0800, Benjamin Kosnik wrote:
> 
> It's my strong preference to have a docs directory with all the HTML and
> .texi files included in the distribution by default. For whatever reason,
> it looks like a copy of the HTML files will be living outside the main
> source tree. This is ok, but I really want to have active HTML
> documentation within the source directory.

Gerald and I have been tossing around thoughts on this.  We're worried that
trying to keep both copies alive and in sync will prove to be painful and
possibly lose information.

I think we should split them up.

It seems that the HTML docs have self-separated into two categories, vaguely:
"main" pages which are mostly viewed via the gnu web server and do not need
to change vary rarely; and "inner" pages which reflect current reality.
As we make changes to the configury, etc, we are consistently editing the
inner pages; this is a Very Good Thing.

(Another way to look at it:  "main" pages are the things we need to have
living on a web server, "inner" pages are more along the lines of "library
documentation that happens to be in html".)

I propose:

    1)  we split the pages along those lines
    2)  make the "main" pages live only in wwwdocs, remove them from v3/docs
    3)  keep the "inner" pages in v3/docs[/html] and either
        a)  remove them from wwwdocs, or
        b)  occasionally push them to wwwdocs and live with the
            inconsistency, or
        c)  make the v3/docs pages available over *some* webserver, and
            link to them from the "main" pages; this would mean going
            partially back to the auto-checkout scheme we had previously
    4)  when users ask the hard questions, we would refer them to the
        "inner" pages on their local disk, since those are the ones we are
        constantly updating (assuming they're using cvs)

For a short-term start, Gerald and I would like to remove from v3/docs:

    download.html
    footer.ihtml
    header.ihtml
    links.html
    mail.html

It seems quite safe to remove these, since there is no information in
them which a person in possesion of the sources doesn't already know.
I'd like to do that ASAP.

I myself would also like to remove index.html, status.html, and thanks.html,
but haven't discussed that with anyone yet.

All those files would fall under (2) in the list above.

For the choices in (3), I have a hankerin' for (a).  On the main pages
viewed over the web, we maybe replace documentation.html with an explanation
that because the docs change so quickly, You The User will need to get the
sources (snapshot or CVS) which will come with the docs.  Options (b) and
(c) seem more painful.

What do you all think?


Phil

-- 
pedwards at disaster dot jaj dot com  |  pme at sources dot redhat dot com
devphil at several other less interesting addresses in various dot domains
The gods do not protect fools.  Fools are protected by more capable fools.

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