This is the mail archive of the
mailing list for the libstdc++ project.
Re: splitting up docs dir (was Re: Doxygen - another sample,preliminary comments)
- To: Phil Edwards <pedwards at disaster dot jaj dot com>
- Subject: Re: splitting up docs dir (was Re: Doxygen - another sample,preliminary comments)
- From: Benjamin Kosnik <bkoz at redhat dot com>
- Date: Fri, 1 Dec 2000 16:05:22 -0800 (PST)
- cc: gdr at codesourcery dot com, pfeifer at dbai dot tuwien dot ac dot at, jason at molenda dot com, libstdc++ at sources dot redhat dot com
Jason I'm cc'ing you on this because you did the initial work to let
libstdc++-v3/docs be under CVS control yet also dynamically pushed out to
the web. I know this was a wierd thing to do but I've found it to be
insanely useful, and am wondering if you can provide some kind of sanity
check for what might be unrealistic demands I am making on Phil and the
other gcc web page maintainers.
Mostly, I'm hoping you can provide insight on this thread. I'd be
interested in what you have to say.
> > 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.
This email I found quite sane. I agree that duplicating two identical HTML
docs files are nasty. Could one be read-only (ie, pushed out and unable to
be modified) and one be read-write?
> 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.
right. I'm hoping we can keep the inner pages within the libstdc++-v3 main
> (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".)
Ok, I think this is a good way to characterize the situation.
> 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
Hmm. Then general web search engines won't find them...
> b) occasionally push them to wwwdocs and live with the
> inconsistency, or
I could live with this.
> 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)
Yuck. Go HTML!
> For a short-term start, Gerald and I would like to remove from v3/docs:
I'm ok with this.
> 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.