This is the mail archive of the libstdc++@gcc.gnu.org mailing list for the libstdc++ project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH] for tr1 progress documentation.

Paolo Carlini wrote:
Hi Ed,

Here is a corrected patch. I should probably wait for more feedback but
I love checking off boxes :oP

I think the patch is mostly fine as an initial commit to start
documenting such work, thanks! A few small changes I suggest before
going ahead (sorry in advance if i'm missing part of the html jargon ;)

------------------------------------------------------------------------

Index: docs/html/ext/tr1.html
===================================================================
--- docs/html/ext/tr1.html (revision 0)
+++ docs/html/ext/tr1.html (revision 0)
@@ -0,0 +1,1689 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
+<head>
+ <title>
+ Changes for TR1
+ Progress on TR1 Implementation
+ </title>
+</head>


In my opinion, this page should be modeled by and large after that for C99:

http://gcc.gnu.org/c99status.html

In particular, we badly need something on top, before the table, a title
and a minimum of introduction to it. I would also mention, for now, that
the table describes the features in mainline.
I'll add an into paragraph and add "Done", "Broken", and "Missing" columns before the notes column. 
+      <li><p>There is an effort underway to add significant extensions to
+         the standard library specification.  The latest version of effort is
+         described in
+         <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf";>
+         Technical Report 1</a>.
+         In this extension some containers from SGI and many initiatives from
+         <a href="http://www.boost.org/";>Boost</a>
+         are making there way into the standard.  In particular, unordered
+         containers, refcounted smart pointers, type traits, fixed-size arrays,
+         tuples, a regular expression engine, a random number engine, special
+         functions, C99 compatability, and more

A few minor points:
1- Watch spelling (compatability/compatiblity), probably better
going through ispell (or similar), in general, for the documentation.
Will do ;-)
2- I think it would be a mistake giving the impression that the
point is ""adding stuff from SGI and Boost"". Indeed, Matt Austern, for
instance, when preparing the specifications of the new unordered
containers had very clear in mind the example of hash_map/has_set;
likewise, we all know that many facilities in TR1 have been proposed by
members of the Boost community. However, with the partial exception of
shared_prt, all the implementation we are offering are completely
unrelated to those codebases (i.e., the original HP/SGI STL, Boost) and
in the end the real, "official", reference for the users of libstdc++-v3
is TR1, nothing else. I think we have only two choices: either we say
nothing about history, or, preferred, we say a minimum about it (thus
mentioning the hashed containers in the original STL, Boost) but we
carefully avoid conveying misleading messages.
I didn't mean to imply that we grabbed code from Boost but was just trying to indicate the history of these changes.
I would personally rather use standard facilities rather than 3rd party libs and would encourage others to as well.

I will mention the Boost heritage in a footnote to shared_ptr in the chart. Other than that I'll clobber the history.
3- Are you running the pages through an HTML checker, this kind of tool?
I'm using http://validator.w3.org. You can either upload a file or point to a URL for them to check.

I hope to have a new patch this evening or tomorrow sometime.

Paolo.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]