Nabble - Boost - Doc

Re: BoostBook and global objects

2008-07-28T22:58:58Z

Eric Niebler wrote:
> Eric Niebler wrote:
>> Eric Niebler wrote:
>>> I can't get Doxygen/BoostBook to emit any documentation about global
>>> objects.
>>
>> Alas, I was unable to prod someone else into action, so I gave it a
>> shot myself.
>
> I took the liberty of committing my changes.

Way back in 2005 I added support in BoostBook for emitting documentation
for global objects (see above). But I failed to add any way to link to
the docs for global objects. I have just corrected that oversight.
BoostBook now has a <globalname> tag for linking to a global object, and
QuickBook now has the corresponding [globalref] directive.

Cheers,

--
Eric Niebler
BoostPro Computing
http://www.boostpro.com

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[boost] BoostBook survey.

2007-08-09T10:05:45Z

If any of you follow the wxWidgets dev list you might have noticed they
are thinking of changing doc format. I pointed out BoostBook as a
possibility. Obviously they would like to see non-Boost uses of
BoostBook. So I'm asking the wonderfully varied Boost user community...

* Do you use BoostBook in some way?
* If so, could you provide an example of how you use it?

If you want I can find a place in our growing list of Boost users
<http://www.boost.org/doc/html/who_s_using_boost_.html>.

--
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Boost-docs is moving to lists.boost.org

2007-07-25T14:39:47Z

Hello all,

We are closing down the boost-docs list at sourceforge.net NOW and
moving the mailing list over to lists.boost.org, where the rest of
the Boost mailing lists live. Anyone interested in Boost
documentation issues should subscribe to the new boost-docs mailing
list at:

http://lists.boost.org/mailman/listinfo.cgi/boost-docs

The boost-docs archives from SourceForge will be moved over to
lists.boost.org very soon; we're waiting on a response to a
SourceForge support request.

- Doug

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-24T08:53:04Z

> Examples are VITAL - without this most peoples reaction is "Huh"?
>
> And there needs to be LOTS of examples, and LOTS of comments saying
> what the examples show, however obvious it may seem to those who
> write the C++ Standard ;-)
>
> What about examples of user defined types?
>
> Perhaps discuss How would you tell if something is default
> constructible? By Test? By examining code?

I completely rewrote the DefaultConstructible concept doc this
morning - it's taken 3 this morning. Please, re-review that one page:
it's here (and it's committed this time).

http://tinyurl.com/2rb477

Changes include:
1. Mostly rewriting the entire concept to get rid of the word
'instance' and it derivatives.
2. Added lots of stuff about initialization - it's probably wrong.
3. Examples.

There are some other changes.

I do have a concern that the idea of default-initialized, zero-
initialized, value-initialized, and uninitialized may dominate the
concept more than the notion of default construct-ability. My
experience is that algorithms requiring default construction will do
so without actual regard for the initial value because they assign
values later, and so an in-depth discussion of initialization within
this concept may be out of place. My gut feeling is that construction
is actually a subtly, different set of concepts than initialization.
For example, there are sets of types that are zero-initialized which
is possibly disjoint from the set that are default-initialized under
some construction syntax. Eh... I don't know. It's all very abstract.

Again, please re-review that one page... Back to graph docs for me.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-24T08:28:05Z

> I have a hard time seeing how "an instance of T is constructed" can be
> construed to be a type -- result, return, or otherwise.

It's not. That was a typo. That would be the result of forgetting to
commit a couple of files before upgrading my workstation and
rebuilding the docs.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-24T04:19:11Z

>-----Original Message-----
>From: boost-docs-bounces@...
>[mailto:boost-docs-bounces@...] On Behalf Of
>Andrew Sutton
>Sent: 23 July 2007 15:05
>To: Boost documentation format, structure, and processing discussion
>Subject: Re: [Boost-docs] stl mini-review
>
>I'm kind of looking for a mini-review of the content and
>presentation. The built version of the docs can be found here:
>
>http://tinyurl.com/3x9s8a
>
>The actual documents include that page (there's text at the bottom),
>the Utilities section, and all pages within that section.

Looking a *really* good start.

>I'm asking the following questions:
>
>1. Is the documentation appropriate?
> a) Is it too abstract? No - it needs to be correct legalize, BUT ...
> b) Is it imprecise or unnecessarily wordy? No - BUT ...
> c) Does each document "flow" correctly from one section
>to the next?
> d) Can (should?) we provide more concrete documentation? Yes & yes.
> e) Can you think of examples that highlight concept
>usage that would be worth including.

Examples are VITAL - without this most peoples reaction is "Huh"?

And there needs to be LOTS of examples, and LOTS of comments saying what the examples show, however obvious it may seem to those who
write the C++ Standard ;-)

What about examples of user defined types?

Perhaps discuss How would you tell if something is default constructible? By Test? By examining code?

> f) Are there spelling/grammar errors?

Not psotted any yet ;-)

> g) Have I obviously plagiarized anything? NO
>
>2. Is the presentation conducive to readability and comprehension?

Yes.

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
+44 1539561830 & SMS, Mobile +44 7714 330204 & SMS
pbristow@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T23:31:43Z

on Mon Jul 23 2007, Andrew Sutton <asutton-AT-cs.kent.edu> wrote:

>>> without initializing it to any particular value.
>>
>> That would make std::vector<int> not default constructible. A
>> constructed vector is always initialized to a particular value.
>
> I had a paragraph about default values, but took it out since there
> doesn't seem to be any strong guarantees on the default value of
> default construction.

There isn't, for builtins. See "value-initialization."

> I think that wording is a hold-over from the
> SGI docs.
>
>> +----------+------------+------------+
>> |Expression|Return |Requirements|
>> | |Type | |
>>
>> I think "Return Type" needs to be "Postcondition" or something.
>
> Perhaps... I stripped the table headers right out of the standard.
> Postcondition would be a more formal way of expressing the third
> column, requirement(s). The SGI docs actually provide considerably
> more in the way of documenting these: An expression name, the
> expression itself, type requirements, return type, precondition,
> postcondition and semantics.
>
> Result type might be more appropriate than return. It's used
> frequently throughout the standard.

I have a hard time seeing how "an instance of T is constructed" can be
construed to be a type -- result, return, or otherwise.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T18:09:44Z

> This is so cool... I think that the STL docs will be one of the
> biggest projects of IBD.

It would be even better if I had remembered to commit all my changes
to the concept docs before unplugging my old server. I guess I'll
have to do that tomorrow morning when I get to school. Damn.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T18:05:25Z

> One of the great things about having language support for concepts in
> ConceptGCC is that it finds all the bugs in other
> formulations... which is to say I suggest you give much more weight to
> the concept definitions from the latest documents and ConceptGCC
> standard library.

Perhaps it would be a better idea to just co-opt the concepts from
the proposed utility extensions rather than simply re-documenting
what's currently present in SGI or ISO docs.

>> A type T is said to be default constructible if it can be
>> instantiated
>
> Careful, we don't "instantiate" types in C++.

Let me see if I can puzzle this out... Templates are instantiated,
types are constructed? Is that more correct? Is there a better way to
say that/?

>
>> without initializing it to any particular value.
>
> That would make std::vector<int> not default constructible. A
> constructed vector is always initialized to a particular value.

I had a paragraph about default values, but took it out since there
doesn't seem to be any strong guarantees on the default value of
default construction. I think that wording is a hold-over from the
SGI docs.

> +----------+------------+------------+
> |Expression|Return |Requirements|
> | |Type | |
>
> I think "Return Type" needs to be "Postcondition" or something.

Perhaps... I stripped the table headers right out of the standard.
Postcondition would be a more formal way of expressing the third
column, requirement(s). The SGI docs actually provide considerably
more in the way of documenting these: An expression name, the
expression itself, type requirements, return type, precondition,
postcondition and semantics.

Result type might be more appropriate than return. It's used
frequently throughout the standard.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T16:49:33Z

on Mon Jul 23 2007, David Abrahams <dave-AT-boost-consulting.com> wrote:

>> A type T is said to be default constructible if it can be
>> instantiated
>
> Careful, we don't "instantiate" types in C++.

Oh, and you should drop "said to be."
This isn't a colloquialism we're describing.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T16:47:37Z

on Mon Jul 23 2007, Andrew Sutton <asutton-AT-cs.kent.edu> wrote:

> I'm combining and paraphrasing three distinct sources: the original
> SGI docs (for basic format and content), the 2003 C++ edition (for
> correctness) and some of the WG docs on concepts.

One of the great things about having language support for concepts in
ConceptGCC is that it finds all the bugs in other
formulations... which is to say I suggest you give much more weight to
the concept definitions from the latest documents and ConceptGCC
standard library.

> A type T is said to be default constructible if it can be
> instantiated

Careful, we don't "instantiate" types in C++.

> without initializing it to any particular value.

That would make std::vector<int> not default constructible. A
constructed vector is always initialized to a particular value.

+----------+------------+------------+
|Expression|Return |Requirements|
| |Type | |
+----------+------------+------------+
|T x | |x is an |
| | |instance of |
| | |T. |
+----------+------------+------------+
|T() |An instance | |
| |of T is | |
| |constructed.| |
+----------+------------+------------+

I think "Return Type" needs to be "Postcondition" or something.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T15:10:20Z

On 7/23/07, Andrew Sutton <asutton@...> wrote:
> > Sorry for quoting Andrew's entire post below, but I really want to
> > endorse it. I consider myself very demanding when it comes to
> > documentation quality, but he's thinking about this at a level beyond
> > where I've been. I agree 100% with the direction in which he's headed
> > and would happily follow him into battle. It's sort of a relief to
> > know he's taken up this cause because now I know I don't have to worry
> > (much) about it ;-)
>
> That's quite an endorsement :)

Yeah :)

> Basically, if you read them over and find something you don't like or
> that could be improved, added, or removed, I'd like to know. Also, if
> anybody would like to contribute... well, the more the merrier. It'll
> be a regular documentation party (which may be a first).

Ok, I want to help you promote the Standard C++ Library Boosted Docs project.
I have add a help request in the "How to help" section of the IBD main
wiki page:

http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#Howtohelp

And an "Active Developers" section on the STL docs main wiki page:

http://svn.boost.org/trac/boost/wiki/StandardCppLibraryDocumentation

It will be good if we can add a detailed "How to help" section to this page.

Once we got all the stubs and we settled down on a style (your
mini-review is a brilliant idea IMO) we can send a mail to the boost
devel list to formally present the project.

This is so cool... I think that the STL docs will be one of the
biggest projects of IBD.

King Regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T12:27:23Z

> Oops... Actually these aren't here at the moment. My computer is
> currently being replaced and I'm in the process of rebuilding it
> right now. Goodbye Vista. Hello Ubuntu. I hope to have it back up
> within an hour or two.

Okay... it's back up. Not that you'll notice much of a difference but
it's not being served off a dual-core machine with 2GB or ram. Yeah,
horsepower :)

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T10:23:37Z

> I'm kind of looking for a mini-review of the content and
> presentation. The built version of the docs can be found here:
>
> http://tinyurl.com/3x9s8a

Oops... Actually these aren't here at the moment. My computer is
currently being replaced and I'm in the process of rebuilding it
right now. Goodbye Vista. Hello Ubuntu. I hope to have it back up
within an hour or two.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T09:50:49Z

> It is possible. For example, in the "Default Constructible"
> section, you could have a section as follows:
>
> Concrete Example of a Default Constructible:
> // T t;
> // T = vector<int>
> // t = a
> vector<int> a;
>
> Should we? I'm not sure. I tutor a lot of students who would not be
> able to use these reference documents for anything useful. Most
> beginners learn by having concrete examples, and I've experienced a
> few blank stares by telling beginners that an object is Assignable
> instead of "it overloads the equals operator" while drawing it on
> the board. The question becomes, "Should beginners bother using
> these docs, or should they learn elsewhere? If they're not learning
> here, where else should they go to learn?"

That's probably a good idea... I do like a good example :) I'm
thinking something like:

Examples

All built-in types are default constructible.

int i;
float f;

Most of classes in the standard library are also default constructible:

std::string s;
std::vector<int> v;
std::istream is;

... Something else using templates and default construction and/or a
user-defined class. I'll work on putting some in tonight to see how
it reads.

> I hope not ;). " The first principle is that you must not fool
> yourself, and you are the easiest person to fool." Bend over
> backwards to cite sources that aren't from the standard and you'll
> be OK.

I'm pretty sure I didn't :) I've actually spent a fair amount of time
working out the wording of those concepts.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T08:51:13Z

On 7/23/07, Andrew Sutton <asutton@...> wrote:

I'm kind of looking for a mini-review of the content and
presentation. The built version of the docs can be found here:

http://tinyurl.com/3x9s8a

The actual documents include that page (there's text at the bottom),
the Utilities section, and all pages within that section.

I'm asking the following questions:

1. Is the documentation appropriate?
a) Is it too abstract?

For my purposes, the docs are crystal clear.

b) Is it imprecise or unnecessarily wordy?

I didn't do a thorough examination, but all of the docs I examined were precise to this intermediate C++ user.

c) Does each document "flow" correctly from one section to the next?
d) Can (should?) we provide more concrete documentation?

It is possible. For example, in the "Default Constructible" section, you could have a section as follows:

Concrete Example of a Default Constructible:
   // T t;
   // T = vector<int>
   // t = a
   vector<int> a;

Should we? I'm not sure. I tutor a lot of students who would not be able to use these reference documents for anything useful. Most beginners learn by having concrete examples, and I've experienced a few blank stares by telling beginners that an object is Assignable instead of "it overloads the equals operator" while drawing it on the board. The question becomes, "Should beginners bother using these docs, or should they learn elsewhere? If they're not learning here, where else should they go to learn?"

There are plenty of beginner C++ books that don't bother with concepts, and there are plenty of advanced C++ books that focus 100% on the standard, but I haven't seen much in-between. This may also indicate that there's no need for the in-between. Does anyone else have thoughts on this issue?

g) Have I obviously plagiarized anything?

I hope not ;). " The first principle is that you must not fool yourself, and you are the easiest person to fool." Bend over backwards to cite sources that aren't from the standard and you'll be OK.

Good work!
Jake

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl mini-review

2007-07-23T08:05:04Z

> Sorry for quoting Andrew's entire post below, but I really want to
> endorse it. I consider myself very demanding when it comes to
> documentation quality, but he's thinking about this at a level beyond
> where I've been. I agree 100% with the direction in which he's headed
> and would happily follow him into battle. It's sort of a relief to
> know he's taken up this cause because now I know I don't have to worry
> (much) about it ;-)

That's quite an endorsement :)

I've been slowly (very slowly) contributing to the massive body of
empty documents that I've committed to the boost_docs project. So far
I've managed to document the five "utility" concepts: default and
copy constructible, assignable, and less than/equality comparable.

I'm combining and paraphrasing three distinct sources: the original
SGI docs (for basic format and content), the 2003 C++ edition (for
correctness) and some of the WG docs on concepts. In fact, most of
the concept docs that I've written so far have a "C++0x" section at
the bottom that gives some perspective on what's probably going to
happen in the future. I think its probably worthwhile to include this
information since its /going/ to happen and we might want to get
people ready for it - and concept docs are the place to do it. Of
course, this it may be inappropriate to provide documents that
straddle 17 years of standard library. (the SGI docs have a 1994
copyright).

I'm kind of looking for a mini-review of the content and
presentation. The built version of the docs can be found here:

http://tinyurl.com/3x9s8a

The actual documents include that page (there's text at the bottom),
the Utilities section, and all pages within that section.

I'm asking the following questions:

1. Is the documentation appropriate?
a) Is it too abstract?
b) Is it imprecise or unnecessarily wordy?
c) Does each document "flow" correctly from one section to the next?
d) Can (should?) we provide more concrete documentation?
e) Can you think of examples that highlight concept usage that would
be worth including.
f) Are there spelling/grammar errors?
g) Have I obviously plagiarized anything?

2. Is the presentation conducive to readability and comprehension?

I actually couldn't think of too many presentation questions, since
most of them apply to the rendering system.

Basically, if you read them over and find something you don't like or
that could be improved, added, or removed, I'd like to know. Also, if
anybody would like to contribute... well, the more the merrier. It'll
be a regular documentation party (which may be a first).

Back to writing graph docs.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: [SVG ICONs] Potentially final visual style andtheme

2007-07-23T02:04:20Z

>-----Original Message-----
>From: boost-docs-bounces@...
>[mailto:boost-docs-bounces@...] On Behalf Of
>Joel de Guzman
>Sent: 22 July 2007 16:00
>To: boost-docs@...
>Subject: Re: [Boost-docs] [SVG ICONs] Potentially final visual
>style andtheme
>
>Jake Voytko wrote:
>> On 7/22/07, Peter Foley <peter@...> wrote:
>>> As John and Joel suggested for the note icon maybe we could
>just use a plain
>>> Notepad and Pencil icon (either with a background like
>Custom Icon Set 6
>>> Note or without). This would mean we could potentially use
>the Blue Circle
>>> with the letter I for the important admonition.
>>>
>>>
>>>
>>> What are people's views on this?
>>
>> That seems like a good compromise to me. If that is the complete set,
>> I'd be happy with that. Good work :)
>
>Yes, I think it's perfect.
>
>pencil+pad == note
>i == important information
>
>Sounds good to me.

And me FWIW.

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
+44 1539561830 & SMS, Mobile +44 7714 330204 & SMS
pbristow@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl docs

2007-07-22T11:09:56Z

Sorry for quoting Andrew's entire post below, but I really want to
endorse it. I consider myself very demanding when it comes to
documentation quality, but he's thinking about this at a level beyond
where I've been. I agree 100% with the direction in which he's headed
and would happily follow him into battle. It's sort of a relief to
know he's taken up this cause because now I know I don't have to worry
(much) about it ;-)

on Fri Jul 20 2007, Andrew Sutton <asutton-AT-cs.kent.edu> wrote:

>> Wow! Great Andrew... this can really fuel the standard docs project.
>
> Yes... There was much rapid typing, and opening of files. Now, my
> wrists hurt, but never before have so many empty files been committed
> to such a great cause :)
>
>> We have been informally discussing the fate of the Standard C++
>> Library Boosted Documentation in our community blog.
>>
>> Jake and Stjepan have made some very important points.
>> One in particular was a revelation for me:
>
> I read those this morning...
>
>> We should move further discussion here.
>
> We could, but I actually prefer the mailing list since this
> discussion is fairly on-topic. I'm going to pick on something Jake
> (Voytko) said:
>
> "I think we may want to split the documentation for each header into
> two discrete segments: reference, and best practices"
>
> This is mostly in the right direction, except that there's a little
> more to it. Many libraries require or provide concept documentation.
> Concise, well-organized, and well-presented concepts are going to be
> critical for C++ developers - more so in the future than now, perhaps.
>
> I would also like to make a distinction between "reference documents"
> and "code-listings". There are a number of libraries that sell their
> API reference material as a simple listing of header files, classes,
> and functions (a la Doxygen). This is a lazy way to write docs and
> isn't any better than looking at the header file. Reference documents
> should have a complete (textual) description of the the function's
> behaviors, its parameters, its preconditions and postconditions (if
> relevant), return values, and exceptions.
>
> And then there's the examples... Each reference doc should contain a
> meaningful example that illustrates best-practice use of the API. And
> what I mean by "meaningul" is that examples should draw from a real
> problem as much as possible. Here's the SGI example of std::vector:
>
> vector<int> V;
> V.insert(V.begin(), 3);
> assert(V.size() == 1 && V.capacity() >= 1 && V[0] == 3);
>
> This is one of the most egregious examples I've ever read. There are
> roughly 25 methods in this class and the example shows 5 - and none
> of them are very useful. Giving meaningful real-world examples helps
> the reader connect with the material since it's showing the
> usefulness of the subject in a relevant way. A good example of using
> a vector might be the creation of a histogram (counting observations)
> since it would rely on the random access properties provided by the
> vector.
>
> Examples of _bad practice_ could follow the "good example". These
> might illustrate things like iterator invalidation. We could also
> have "snippets" that show the best way to perform common tasks (like
> erasing a range of elements).
>
> MSDN actually does a pretty good job with reference docs. That should
> probably serve as the model.
>
> I'll re-post this as a comment on the blog-site just in case.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[IBD] Weekly news: 2007-07-11 to 2007-07-17

2007-07-22T10:51:27Z

==================================================

Hi Boost, Once a week, we will send you a brief of
our work for the Improving Boost Docs project.
We need more hands, join us!
We are waiting you on the boost-docs list.

Project Wiki:
http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs

RSS news feed:
http://beta.boost.org/development/ibd_news.rss

Community Blog:
http://improving-boost-docs.blogspot.com

==================================================

A bussy week
-------------------------------------------------------------------------------------

Sorry for the delay, It was a busy week. I have
started to promote IBD in Argentina... we may get
some friendly hands from my country in the future.

Kudos to all IBDers... the boost-docs list activity is
truly impressive.

2007-07-17
-------------------------------------------------------------------------------------

* Proofreading of the IBD Wiki is almost complete

Kudos to Jake and Paul!

more...
http://tinyurl.com/3234qk

* Kai joins IBD

He will be working at the "Trac Syntax Coloring Project".
Thanks you so much for jumping in!

more...
http://tinyurl.com/3d6mwe

2007-07-16
-------------------------------------------------------------------------------------

* IBD welcomes Kai Brüning

It will be great to count with his help. Lets work to make him feel
comfortable in the Boost community.

more...
http://tinyurl.com/2to8bg

2007-07-15
-------------------------------------------------------------------------------------

* Translation project moved to Helping Boost Authors

The translation project is now part of the new section
"Helping Boost Authors". We hope this section will become the main
communication channel between Boost Authors and IBD developers.

more...
http://svn.boost.org/trac/boost/wiki/HelpingBoostAuthors

2007-07-14
-------------------------------------------------------------------------------------

* Helping Boost Authors

We have a new resource at IBD: a section in the project Wiki called
"Helping Boost Authors".
This section is a bazaar of friendly hands. We are teachers, experienced
users, native English speakers and artists. We want to offer our help to
Boost authors to improve their documentation.

more...
http://svn.boost.org/trac/boost/wiki/HelpingBoostAuthors

2007-07-13
-------------------------------------------------------------------------------------

* Documentation Best Practices

The first guideline was added to the section "Documentation Best Practices".
There are currently more documents to add here, we will try to fill this
section with useful information for Boost Authors.

more...
http://svn.boost.org/trac/boost/wiki/DocumentationBestPractices

2007-07-12
-------------------------------------------------------------------------------------

* Proofreading of IBD Wiki starts

Jake and Paul first project will be proofread the IBD Wiki pages.

more...
http://tinyurl.com/3786jf

2007-07-11
-------------------------------------------------------------------------------------

* Glyn joins the community Blog

We are eagerly waiting to read you.

more...
http://improving-boost-docs.blogspot.com

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: [SVG ICONs] Potentially final visual style and theme

2007-07-22T09:00:03Z

Jake Voytko wrote:

> On 7/22/07, Peter Foley <peter@...> wrote:
>> As John and Joel suggested for the note icon maybe we could just use a plain
>> Notepad and Pencil icon (either with a background like Custom Icon Set 6
>> Note or without). This would mean we could potentially use the Blue Circle
>> with the letter I for the important admonition.
>>
>>
>>
>> What are people's views on this?
>
> That seems like a good compromise to me. If that is the complete set,
> I'd be happy with that. Good work :)

Yes, I think it's perfect.

pencil+pad == note
i == important information

Sounds good to me.

Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: [SVG ICONs] Potentially final visual style and theme

2007-07-22T08:53:28Z

On 7/22/07, Peter Foley <peter@...> wrote:
> As John and Joel suggested for the note icon maybe we could just use a plain
> Notepad and Pencil icon (either with a background like Custom Icon Set 6
> Note or without). This would mean we could potentially use the Blue Circle
> with the letter I for the important admonition.
>
>
>
> What are people's views on this?

That seems like a good compromise to me. If that is the complete set,
I'd be happy with that. Good work :)

Jake

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: [SVG ICONs] Potentially final visual style and theme

2007-07-22T04:14:42Z

All,

The consensus seems to be that we:

* Still need to find an appropriate important icon;

* The light globe would be more suited for use as the Tip Admonition

- Either the Tango light globe; or

- Custom Icon set 2 Tip icon;

* The other icons are fine.

As John and Joel suggested for the note icon maybe we could just use a plain Notepad and Pencil icon (either with a background like Custom Icon Set 6 Note or without). This would mean we could potentially use the Blue Circle with the letter I for the important admonition.

What are people’s views on this?

Peter.

Re: [SVG ICONs] Potentially final visual style andtheme

2007-07-22T03:35:04Z

Hi Paul,

Thanks for the feedback!

I am about to send out another email with other options taking into consideration what you, John, Joel and Cédric have said.

Thanks,

Peter.

From: boost-docs-bounces@... [mailto:boost-docs-bounces@...] On Behalf Of Paul A Bristow
Sent: Saturday, 21 July 2007 11:38 PM
To: 'Boost documentation format, structure, and processing discussion'
Subject: Re: [Boost-docs] [SVG ICONs] Potentially final visual style andtheme

From: boost-docs-bounces@... [mailto:boost-docs-bounces@...] On Behalf Of Peter Foley
Sent: 21 July 2007 11:25
To: Boost documentation format, structure, and processing discussion
Subject: [Boost-docs] [SVG ICONs] Potentially final visual style and theme

I have added custom icon set 7 and 8 which includes an alternate to the note icon and two “important” admonition icons. There is now at least one icon for each admonition. Also there are both a colour icon and a black and white icon for each symbol (see Key Points below).

Key points overall for the icons:

1.            Each admonition background is:

                1.1 - A different shape (except for Note and Tip (see footnote 1 below)). They are Circle x2, Square, Triangle and Hexagon. This should provide a visual guide even for those who are (partially) colour blind;

                1.2 - A different colour (except for Note and Important (see footnote 2 below)). They are Black, Blue, Black, Orange and Red.

2.            Each admonition foreground icon shape is visually different:   GOOD

                2.1 -Note – is a light globe

                2.2 -Tip – is the letter “i”

                2.3 -Important – is the star/asterisk character

                2.4 -Caution – is an exclamation mark

                2.5 -Warning/Danger – is the word stop

A verbal visual description for each Admonition is as follows:

*             Note – “Black Circle” background with “light globe switched on” foreground

*             Tip – “Blue Circle” background with “white letter I” foreground

*             Important – “Black Square” background with “white star/asterisk character” foreground

*             Caution – “Orange Triangle Border” background with “black exclamation mark character” foreground

*             Warning/Danger – “Red Hexagon” background with “the white word stop” foreground

I have taken the liberty of updating the current consensus section (http://tinyurl.com/2k7mw7) to show my preference for the icons. The only change from the last update is the different note icon (I changed it from Custom Icon Set 2 Tip to Custom Icon Set 7 Note (see footnote 1 for the rational of this switch)) and I have added both the colour and black and white versions for the Important Admonition icons. I have updated this section for people to more easily view the overall proposed set.

I also agree strongly that tip and important are the wrong way round.  i means information == note for me.

And the light bulb means tip to me. I like the tango or custom 2 MUCH more than the current choice one.

I don't like Important icon at all. An arrow would be OK, perhaps the hand with finger? But I don't think we need an important icon really.

I believe that besides a couple of minor visual tweaks (fixing up icon shadows, ensuring that the SVG files are scaled correctly, maybe slightly increasing the size of the letter “I” for the Tip admonition) these icons are ready for use!

I am hoping that the title of this post will encourage people to look at these icons and express what they like or dislike about them and potentially how to improve them.

As an aside is this something that should have a wider dissemination for people to express their views on (ie to the Boost Dev list) as these icons will be used in any Quickbook documentation that library authors create for their documentation or is a consensus on this list sufficient?

I think we've discussed enough ;-)

Let me know what you think.

Thanks,

Peter.

Footnote 1 – I personally think that instead of using the light globe as shown as Custom Icon Set 2 Tip, we should use the Custom Icon set 7 Note icon. This will ensure that we have a similar look and feel for all of the admonition icons (ie they each have a clear background shape associated with the icon and it will be easier for colour blind people to see the outline of the shape).

I don't like it at all :-(

Footnote 2 – Although discussions on the list suggested that the colours for the Important, Caution and Warning/Danger admonitions be Yellow -> Orange -> Red I found that I could not get a Yellow icon that would look right on a page with a white background. I have included one of the better yellow icons as the Important icon in Custom Icon set 7.

I'm fine with red - it is the international road sign colour.

Re: [SVG ICONs] Potentially final visual style andtheme

2007-07-22T03:33:06Z

Hi Joel,

Thanks for the feedback.

I will move the light globe icon into the Tip slot =p.

Thanks,

Peter.

> -----Original Message-----
> bounces@...] On Behalf Of Joel de Guzman
> Sent: Saturday, 21 July 2007 10:09 PM
>
> Cédric Venet wrote:
> > I would personally switch between the note and tip icon. In my
> > experience the light globe is usually used to indiquate tips and
> tricks.
>
> I think I agree with Cédric. A quick google-image
> search for "tip icon" gives you many light-bulb
> hits:

Re: [SVG ICONs] Potentially final visual style andtheme

2007-07-22T03:31:26Z

Hi John,

Thanks for the feedback!

> bounces@...] On Behalf Of John Maddock
>
> Peter Foley wrote:
> > Let me know what you think.
>
> Well... I like them except for the "note" and the "important" icons
> which I
> really don't like at all, sorry :-(

Thats ok =p, hence me asking for feedback. Personally I was struggling
to come up with an idea for the important icon myself I think I trapped
my thinking by trying to have a different shape and colour for each
icon!

>
> Actually, aren't the note and tip icons the wrong way around anyway?

Your right. I somehow flipped them around even though logically I
thought it was strange myself.

>
> Anyhow, from the tip column I do like the tango version, custom icon
2,
> or
> custom icon 6.
>
> For the "important" icon, I'm not that keen on any of the
alternatives,
> sorry :-( Just a suggestion, but how about a right-pointing arrow?
> Same as
> the navigation right arrow, but a different colour (orange maybe)?

I agree with what you are saying I will send a separate email with my
thoughts on the above.

Thanks,

Peter.

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: [SVG ICONs] Potentially final visual style andtheme

2007-07-22T03:28:56Z

Hi Cédric,

Thanks for the feedback. From reading the other comments back so far it seems that people agree. That the Tip and Note icons are potentially around the wrong way.

Peter.

From: boost-docs-bounces@... [mailto:boost-docs-bounces@...] On Behalf Of Cédric Venet
Sent: Saturday, 21 July 2007 9:57 PM
To: 'Boost documentation format, structure, and processing discussion'
Subject: Re: [Boost-docs] [SVG ICONs] Potentially final visual style andtheme

I would personally switch between the note and tip icon. In my experience the light globe is usually used to indiquate tips and tricks.

Just my 2 cents

Cédric Venet

Re: stl docs

2007-07-21T21:42:04Z

David Abrahams wrote:
> on Fri Jul 20 2007, "Jake Voytko" <jakevoytko-AT-gmail.com> wrote:
>
>> It appears that it costs about 300 dollars to purchase the standard
>> from ISO.org. Ouch.
>
> You can get a PDF for $18 from the ANSI document store,
> <http://webstore.ansi.org/> (which appears to be down for maintenance
> at the moment).

It seems to be up to $30. Anyway, here's a link,

http://tinyurl.com/3yrq9o
(or
http://webstore.ansi.org/RecordDetail.aspx?sku=INCITS%2fISO%2fIEC+14882-2003)

Best regards,

João

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl docs

2007-07-21T12:49:37Z

Dave,

My brief searches didn't turn up any alternatives (though I didn't look very hard, as I quickly found it through Google and stopped at that point). I'll gladly put the money down. Thanks for letting us know! 300 simply isn't affordable for this student, but I think I can find 18 dollars lying around somewhere :)

Jake

On 7/21/07, David Abrahams <dave@...> wrote:

on Fri Jul 20 2007, "Jake Voytko" <jakevoytko-AT-gmail.com> wrote:

> It appears that it costs about 300 dollars to purchase the standard
> from ISO.org. Ouch.

You can get a PDF for $18 from the ANSI document store,
<http://webstore.ansi.org/> (which appears to be down for maintenance
at the moment).

You can get it for $74 as a hardcover book
< http://www.amazon.com/exec/obidos/tg/detail/-/0470846747/> for
example.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl docs

2007-07-21T12:29:59Z

on Fri Jul 20 2007, "Jake Voytko" <jakevoytko-AT-gmail.com> wrote:

> It appears that it costs about 300 dollars to purchase the standard
> from ISO.org. Ouch.

You can get a PDF for $18 from the ANSI document store,
<http://webstore.ansi.org/> (which appears to be down for maintenance
at the moment).

You can get it for $74 as a hardcover book
<http://www.amazon.com/exec/obidos/tg/detail/-/0470846747/> for
example.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: stl docs

2007-07-21T12:24:38Z

on Fri Jul 20 2007, "Jake Voytko" <jakevoytko-AT-gmail.com> wrote:

> On 7/20/07, Andrew Sutton <asutton@...> wrote:
>
> >> So I think we should use these.
> >
> > Please use the C++ standard instead. It is the only authoritative
> > source, and the SGI docs are not always consistent with it.
>
> Good point. Out of which version of the standard should we be
> referencing? I have a copy of the 1998 first edition floating around
> on my laptop, but I can't seem to tell if that's the most recent
> published version. I'd hate to be writing docs for something a couple
> years out of date.
>
> Andrew Sutton
> asutton@...
>
> If that is the most recent version, could you post that to the
> Vault, or an otherwise accessible location? I feel that that could
> come in handy for this project :)

Please don't. That would be illegal, as it's under copyright.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

How to get a real newline?

2007-07-21T08:15:54Z

There seem to be some places where we *really* want a newline.

We now get

math.qbk:203: warning: in column:76, [br] and \n are deprecated.
...

What is the 'right' (not deprecated!) way to do this now?

Create/use a template?

Thanks

Paul
---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
+44 1539561830 & SMS, Mobile +44 7714 330204 & SMS
pbristow@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: [SVG ICONs] Potentially final visual style and theme

2007-07-21T07:37:45Z

From: boost-docs-bounces@... [mailto:boost-docs-bounces@...] On Behalf Of Peter Foley
Sent: 21 July 2007 11:25
To: Boost documentation format, structure, and processing discussion
Subject: [Boost-docs] [SVG ICONs] Potentially final visual style and theme

I have added custom icon set 7 and 8 which includes an alternate to the note icon and two “important” admonition icons. There is now at least one icon for each admonition. Also there are both a colour icon and a black and white icon for each symbol (see Key Points below).

Key points overall for the icons:

1.            Each admonition background is:

                1.1 - A different shape (except for Note and Tip (see footnote 1 below)). They are Circle x2, Square, Triangle and Hexagon. This should provide a visual guide even for those who are (partially) colour blind;

                1.2 - A different colour (except for Note and Important (see footnote 2 below)). They are Black, Blue, Black, Orange and Red.

2.            Each admonition foreground icon shape is visually different:   GOOD

                2.1 -Note – is a light globe

                2.2 -Tip – is the letter “i”

                2.3 -Important – is the star/asterisk character

                2.4 -Caution – is an exclamation mark

                2.5 -Warning/Danger – is the word stop

A verbal visual description for each Admonition is as follows:

*             Note – “Black Circle” background with “light globe switched on” foreground

*             Tip – “Blue Circle” background with “white letter I” foreground

*             Important – “Black Square” background with “white star/asterisk character” foreground

*             Caution – “Orange Triangle Border” background with “black exclamation mark character” foreground

*             Warning/Danger – “Red Hexagon” background with “the white word stop” foreground

I have taken the liberty of updating the current consensus section (http://tinyurl.com/2k7mw7) to show my preference for the icons. The only change from the last update is the different note icon (I changed it from Custom Icon Set 2 Tip to Custom Icon Set 7 Note (see footnote 1 for the rational of this switch)) and I have added both the colour and black and white versions for the Important Admonition icons. I have updated this section for people to more easily view the overall proposed set.

I also agree strongly that tip and important are the wrong way round.  i means information == note for me.

And the light bulb means tip to me. I like the tango or custom 2 MUCH more than the current choice one.

I don't like Important icon at all. An arrow would be OK, perhaps the hand with finger? But I don't think we need an important icon really.

I believe that besides a couple of minor visual tweaks (fixing up icon shadows, ensuring that the SVG files are scaled correctly, maybe slightly increasing the size of the letter “I” for the Tip admonition) these icons are ready for use!

I am hoping that the title of this post will encourage people to look at these icons and express what they like or dislike about them and potentially how to improve them.

As an aside is this something that should have a wider dissemination for people to express their views on (ie to the Boost Dev list) as these icons will be used in any Quickbook documentation that library authors create for their documentation or is a consensus on this list sufficient?

I think we've discussed enough ;-)

Let me know what you think.

Thanks,

Peter.

Footnote 1 – I personally think that instead of using the light globe as shown as Custom Icon Set 2 Tip, we should use the Custom Icon set 7 Note icon. This will ensure that we have a similar look and feel for all of the admonition icons (ie they each have a clear background shape associated with the icon and it will be easier for colour blind people to see the outline of the shape).

I don't like it at all :-(

Footnote 2 – Although discussions on the list suggested that the colours for the Important, Caution and Warning/Danger admonitions be Yellow -> Orange -> Red I found that I could not get a Yellow icon that would look right on a page with a white background. I have included one of the better yellow icons as the Important icon in Custom Icon set 7.

I'm fine with red - it is the international road sign colour.

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: [SVG ICONs] Potentially final visual style and theme

2007-07-21T06:08:43Z

Cédric Venet wrote:
> I would personally switch between the note and tip icon. In my
> experience the light globe is usually used to indiquate tips and tricks.

I think I agree with Cédric. A quick google-image
search for "tip icon" gives you many light-bulb
hits:

http://tinyurl.com/yudxnn

while "note icon" gives you many pencil-pad hits:

http://tinyurl.com/2x8s2z

That is my preference, BTW, but the (i) is ok, and the first
thing that I think of is: i==information.

Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

Re: [SVG ICONs] Potentially final visual style and theme

2007-07-21T06:08:43Z

Peter Foley wrote:
> Let me know what you think.

Well... I like them except for the "note" and the "important" icons which I
really don't like at all, sorry :-(

Actually, aren't the note and tip icons the wrong way around anyway?

Anyhow, from the tip column I do like the tango version, custom icon 2, or
custom icon 6.

For the "important" icon, I'm not that keen on any of the alternatives,
sorry :-( Just a suggestion, but how about a right-pointing arrow? Same as
the navigation right arrow, but a different colour (orange maybe)?

HTH, John.

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs