Mailing-List: contact stdcxx-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: stdcxx-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: local policy)
Content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Subject: RE: [RFC] Apache "look and feel" for stdcxx docs
Date: Wed, 29 Aug 2007 09:53:02 -0600
Message-ID: 
 <C8506D6098A6F545BA3745D0CE359E830184A258@qxvcexch01.ad.quovadx.com>
In-Reply-To: <46C3D56C.3030302@roguewave.com>
Thread-Topic: [RFC] Apache "look and feel" for stdcxx docs
Thread-Index: Acffv9QzuAShni1ESY2+90YsbUXgsgKknTUQ
From: "Marc Betz" <mbetz@roguewave.com>
To: <stdcxx-dev@incubator.apache.org>

Hi, everyone,

Here is my take on the feedback returned on my changes to the
documentation:

- RE banner: I am entirely agreeable to a prettier banner, but that=20
  request needs the talents of a graphics designer. That is most
  definitely not me. Does anyone know of one willing to contribute a
  bit of time?
- RE collapsible TOC in navigation pane: this would require JavaScript.=20
  We have not used JavaScript at Rogue Wave so I don't know anything
about=20
  it, although I imagine I could pick it up pretty quickly, at least for

  something as common as this. We do not use JavaScript because our
documentation
  has always deliberately used very plain vanilla HTML to guarantee it
will
  display well in any browser. Myself, I would suggest keeping it that
way.
- RE buttons: these do not play much part in the frame view, but they
are
  needed in the No Frames view. We could, of course, just forget about
the=20
  No Frames view, but I think there are still those who prefer it.
- RE incomplete sample: you can get a complete copy of both the
reference
  and user guides by downloading the zip archive at:=20
  http://betzmarc.googlepages.com/stdcxx.=20
  I would just have put a viewable version up there except I cannot=20
  figure out how to upload multiple files, and I am certainly not going=20
  to do it one at a time.

I would like to suggest that we commit these documents as they are
currently=20
so I can get busy on cleansing the documents of references to Rogue
Wave,=20
SourcePro, and modules. Then we can fiddle with the format some more
later.=20
Is that agreeable? If so, could someone do it?

Marc

-----Original Message-----
From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
Sent: Wednesday, August 15, 2007 9:41 PM
To: stdcxx-dev@incubator.apache.org
Subject: Re: [RFC] Apache "look and feel" for stdcxx docs

Liviu Nicoara wrote:
> Martin Sebor wrote:
>> Liviu Nicoara wrote:
>>> Martin Sebor wrote:
>> Which list? Is there any project that you liked in particular?
>=20
> http://directory.apache.org the most.

You mean the top banner? I like it okay but I like some others better.
If I had to pick one it would probably be Maven (maven.apache.org).
Not necessarily the graphic on the right but the overall design of the
banner.

>=20
>>
>> FWIW, I like the Web interface to the Standard C++ Library=20
>> documentation for IBM XLC/C++ 9.0, especially the expandable=20
>> navigation frame on the left.
>=20
> Yes, functionally it is complete and it provides a good user
experience.
>=20
>  From an aesthetic point of view it could use a bit of color --=20
> perhaps a comfortable, subtly colored background, more eye-pleasing
icons, etc.

Sure. That's always a matter of personal preference but I agree that the
predominant black/white/gray makes it a little dull.

>=20
> Also, it wouldn't hurt to have browser-neutral html as advocated here:
>=20
> http://www.anybrowser.org/

I agree. That shouldn't be something new, though. AFAICT, we're already
there.

>=20
> E.g., my Firefox renders IBM's site poorly (overlapping text, frames,=20
> etc.).

I don't see any serious problems in my browsers (Seamonkey 1.0.9 or
FireFox 1.5.0.12) but I can imagine that the navigation tree might give
some browsers trouble. We're also constrained by Marc's schedule as to
how fancy we can get in these improvements.

Martin