Proposed man pages: <vector> sample, RFC

[Rich Churcher <churcher at ihug dot com dot au>]

[ I'm sorry this got so long.  If some list subscribers don't want to
  read threads regarding documentation, or don't have time, I'll place
  the "man pages" string in the subject for threads I start
  to assist with scoring/filtering ]

Ok.  I've revisited the thread on this list (back in June) discussing man page
documentation, which begins at:

  http://sources.redhat.com/ml/libstdc++/2000-q2/msg00832.html

I didn't read it very carefully then, but I have now.  There are
several good points made, not least of which are concerns about
duplicating SGI's HTML documentation (we shouldn't) and considering
texinfo format (we should).

<vector> serves to represent the challenge which should apply across
all V3 documentation - how to provide sufficient information to
library users without duplicating more complete standard library
authorities (Stroustrup, et. al.)  

I don't want to present this as a fait accompli - just an idea that
needs constructive criticism from wiser minds.  I put it together
under the premise that, while a V3 user might have plenty of
standard library documentation to hand, s/he may have need of:

  * a quick reference ("man vector", "info libstdc++")
  * an assurance of standards compliance in a certain area
  * a guide to buggy or incomplete areas (hopefully few!)
  * coverage of implementation-defined areas and extensions
  * pointers to more detailed information

Here goes...

NAME
  std::vector

DEFINITION
  namespace std {
    template <class T, class Allocator = allocator<T> >
    class vector {
      // ...
    }
  }

SYNOPSIS
  #include <vector>

  vector< T > v;
  vector< T > v( size_type n, const T& value = T() );
  vector< T > v( InputIterator first, InputIterator last );
  vector< T > v( const vector< T >& x );

  vector::allocator_type may be supplied as the second template
  argument.

DESCRIPTION
  libstdc++-v3 uses SGI's implementation of vector.  Further
  documentation is here:

    http://www.sgi.com/Technology/STL/Vector.html

  [ More implementation details, if necessary... ]

COMMENTS

  [ Refer to current standard working group issues? ]

PROTOTYPES 
  [ Should this section even exist? Might be useful as a quick
    reference. Obviously, copied straight from the standard. ]

  iterator begin();  const_iterator begin() const;
  iterator end();    const_iterator end() const;
  reverse_iterator rbegin();    const_reverse_iterator rbegin() const;
  reverse_iterator rend();      const_reverse_iterator rend() const;

  size_type size() const;   size_type max_size() const;

  void resize(size_type sz, T c = T());   size_type capacity() const;
  bool empty() const;
  void reserve(size_type n);

  reference operator[](size_type n);   
  const_reference operator[](size_type n) const;
  const_reference at(size_type n) const;
  reference at(size_type n);
  reference front();   const_reference front() const;
  reference back();    const_reference back() const;

  void push_back(const T& x);   void pop_back();
  iterator insert(iterator position, const T& x);
  void insert(iterator position, size_type n, const T& x);

  template <class InputIterator>
  void insert(iterator position, 
              InputIterator first, InputIterator last);

  iterator erase(iterator position);
  iterator erase(iterator first, iterator last);
  void swap(vector<T,Allocator>&);
  void clear();

COMPLIANCE 
  Fully compliant with ISO/IEC 14882:1998(E).  See standard
  document section 23.2.4, p482.

FILES
  ${prefix}/include/g++-v3/vector
  ${prefix}/include/g++-v3/bits/std_vector.h
  ${prefix}/include/g++-v3/bits/stl_vector.h

SEE ALSO
  queue(3), deque(3) [ ... etc ]


Productive criticism at this point includes shooting the whole idea
down in flames :o) let's be realistic here.  However, I think if we
can find a simple format that applies across the board - without
getting bogged down in reproducing too much of the standard - this
could work.

-- 
Cheers,
Rich.