Re: [boost] New boost user

From: Beman Dawes (beman_at_[hidden])
Date: 2000-10-09 15:58:40

At 12:48 PM 10/9/2000 -0500, Jeff Squyres wrote:

 >On Mon, 9 Oct 2000, Beman Dawes wrote:
 >
 >> Alternately, a src sub-directory could appear in each library's
 >> directory in libs.  But I think your suggestion above is better - it
 >> is probably clearer to someone just looking at the directory tree.
 >>
 >> What do others think?  Should we add a src sub-directory, containing
 >> sub-directories (with same name as under /libs) for each library which
 >> needs source code compiled before use?
 >
 >Jeremy Siek, William Kempf, and I have been discussing this off the list
 >for a few days now in the attempt to get some working fodder to post back
 >to the list.  We're not in complete agreement, but this message seems 
like
 >a good one to reply to with what we came up with so far.

Thanks for helping with this!

There are some requirements which may not be obvious to everyone:

*  The web site, CVS repository, distribution file (.zip), and internal web 
site tool (FrontPage) directory structures must be the same.  This allows 
internal processes (like updating the web site, creating the .zip file, 
backups, and various CVS operations) to work automatically.  This also 
allows anyone to mirror the site (as some already do on their internal 
LAN's) simply by loading and unzipping the distribution file.

*  Web site size is a factor; that's why we don't post boost_all as both 
.zip and .gz files.  If I can ever get a faster connection, particularly an 
"always on" one, that may change.

*  While we can and will improve the end user's experience, we can't do 
that at the expense of alienating developers. CVS is bad enough.

 >It's a bit more than a "least resistance" approach, so there will likely
 >be some strong feelings here.  :-)  The intent was to make it a "more
 >standardized" tree overall -- not a *completely* standardized tree (i.e.,
 >individual library authors should still have a considerable amount of
 >freedom), but at least have something that can potentially be put in the
 >boost guidelines.  I can't speak for Windows source code distributions,
 >but my contributions were strongly influenced by seeing countless unix
 >.tar.gz source code distributions over the years.
 >
 >Notation: I use $top_srcdir, below, to indicate the directory that the
 >boost distribution was expanded into.
 >
 >(Bill/Jeremy, feel free to chime in if I get anything wrong)
 >
 >-----
 >
 >There are 2 issues: a potential build process and the boost directory
 >structure.  It seems that the directory structure should probably be
 >discussed first, since it will influence the build process much more than
 >vice versa.  So I'll save the build process discussion for a different
 >post.
 >
 >
 >*** Top-level boost distribution directory:
 >
 >We're talking about the directory structure, but I specifically mention 2
 >files since they should also be part of the distribution (and others have
 >mentioned them, I think), and should have standardized names:
 >
 >- A brief README file.  It potentially lists the libraries that are
 >included, gives a very brief overview of each (2-3 sentences), and says
 >"go see the full docs [wherever they are located] for more 
information."
 >It also has some reference to wherever the build docs are located.
 >Probably also lists things like: the date/version of this distribution,
 >the web site URL, the egroups address, etc.

I think we should stick to HTML as our documentation format.  If we add a 
readme file, it should be totally static and just point people to the 
HTML.  The HTML should already include all of the information you mention 
above.  A readme file which has to change each distribution will be a 
maintenance headache.   We certainly could add a readme file that says:

"For access to all documentation, view index.htm in this directory with a 
web browser program such as Netscape Navigator or Internet Explorer."

 >
 >- A brief LICENSE file.  It either has a top-level license, or -- what
 >someone mentioned a few posts ago -- lists the minimum requirements that
 >covers those sub-libraries that don't have a specific license.  Someone
 >with legal experience would be helpful here...

Yes, we really could use some help.  Does ND have a law school?

 >- Leave the current "boost" subdirectory as it is.
 >
 >- Rename the "libs" directory to be "src".  The rationale here is that
 >"lib" and "libs" tend to imply directories that contain binaries.  The
 >name "src" (or "source", or "sources", or ...?) pretty much states that
 >this directory will contain files that need to be compiled.

We need to think about that some more.  Ed Brey's point about being able to 
select a directory for CVS updates is important.

 >- Move all .gif, .htm files, and the "more" and "people" subdirectories 
to
 >a new subdirectory named "html" (or "www", or "docs", or "www.boost.org",
 >or ...?).  The rationale here is that the docs don't need to start at the
 >top-level directory (they clutter up $top_srcdir, IMHO); the README file
 >can point to wherever they begin.

While it sounds like a good idea remove any other HTML files from the top 
level directory, the index.htm file has to stay there due to web site 
requirements.

Anyhow, thanks for the suggestions!  I want to go back and read the CONS 
docs and the ScCons proposal.  Because they are not as limited as make, we 
may be worrying unnecessarily about some of these directory issues.  For 
example, people won't have such high expectations for seeing src and libs 
directories if they see the high level ScCons file in the top level 
directory.

--Beman