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

[Benjamin Kosnik <bkoz at 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
source repository.

> (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:
> 
>     download.html
>     footer.ihtml
>     header.ihtml
>     links.html
>     mail.html

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.

Right.

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

Sounds fine.

-benjamin