From 49923e9f6a76406fb3c8aed3ccbf6fd665d589f8 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Sat, 10 Nov 2007 14:54:18 +0000 Subject: [PATCH] Remove a couple of html files that have been added to the beta site. Refs #1354, #1357. [SVN r40986] --- header.htm | 103 ------ lib_guide.htm | 931 -------------------------------------------------- 2 files changed, 1034 deletions(-) delete mode 100644 header.htm delete mode 100644 lib_guide.htm diff --git a/header.htm b/header.htm deleted file mode 100644 index 3df5cee..0000000 --- a/header.htm +++ /dev/null @@ -1,103 +0,0 @@ - - - - - -Boost Header policy - - - - - - - - - - - - - - - - -
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
-

Boost Header Policy

-

Header files are the place where a library comes into contact with user code -and other libraries.  To co-exist peacefully and productively, headers must -be "good neighbors".

-

Here are the standards for boost headers.    Many of -these are also reasonable guidelines for general use. -

-

Sample Header

-
//  Boost general library furball.hpp header file ---------------------------//
-
-  < Copyright and license notice, as indicated in the license page >
-
-//  See http://www.boost.org/ for latest version.
-
-#ifndef BOOST_FURBALL_HPP
-#define BOOST_FURBALL_HPP
-
-namespace boost {
-
-//  Furball class declaration  -----------------------------------------------//
-
-  class furball
-  {
-    public: 
-      void throw_up();
-    private:
-      int whatever;
-  };  // furball
-
-} // namespace
-
-#endif  // include guard
-

Coding Style

-

The alert reader will have noticed that the sample -header employs a certain coding style for indentation, positioning braces, -commenting ending braces, and similar formatting issues.  These stylistic -issues are viewed as personal preferences and are not part of the Boost Header -Policy.

-
-

Revised 02 October, 2003

- -

© Copyright Beman Dawes 1998

-

- Distributed under the Boost Software License, Version 1.0. (See - accompanying file LICENSE_1_0.txt or copy - at http://www.boost.org/LICENSE_1_0.txt) -

- - - - \ No newline at end of file diff --git a/lib_guide.htm b/lib_guide.htm deleted file mode 100644 index f258260..0000000 --- a/lib_guide.htm +++ /dev/null @@ -1,931 +0,0 @@ - - - - - Boost Library Requirements and Guidelines - - - - - - - - - - - - - - - - - -
- boost.png (6897 bytes) - - Home - - - Libraries - - People - - - FAQ - - More -
-

- - Boost Library Requirements and Guidelines -

-

- Introduction
- Requirements
-     License requirements
-     Portability requirements
- -     Ownership
- Guidelines
-     Design and - programming
-     Directory structure and - filenames
-     Naming - consistency
- -     Documentation
- Rationale
-     Exception-specification rationale
-     Naming conventions rationale
-     Source code fonts - rationale
- -     Tabs rationale
-     ECMAScript/JavaScript - rationale
-     Rationale - rationale
-     Acknowledgements - rationale -

- -

- Introduction -

-

- This page describes requirements and guidelines for the content of a - library submitted to Boost. -

-

- See the Boost Library Submission - Process page for a description of the process involved. -

- -

- Requirements -

-

- To avoid the frustration and wasted time of a proposed library being - rejected, it must meets these requirements: -

- -

- There's no requirement that an author read the mailing list for a time - before making a submission. It has been noted, however, that submissions - which begin "I just started to read this mailing list ..." seem to fail, - often embarrassingly. -

-

- License requirements -

-

- The preferred way to meet the license requirements is to use the Boost Software License. See license information. If for any reason you do not - intend to use the Boost Software License, please discuss the issues on the - Boost developers mailing list first. -

- -

- The license requirements: -

- -

- Portability requirements -

- -

- Since there is no absolute way to prove portability, many boost submissions - demonstrate practical portability by compiling and executing correctly with - two different C++ compilers, often under different operating systems.  - - Otherwise reviewers may disbelieve that porting is in fact practical. -

-

- Ownership -

-

- Are you sure you own the library you are thinking of - submitting?   "How to Copyright Software" by MJ Salone, Nolo - Press, 1990 says: -

- -
-

- Doing work on your own time that is very similar to programming you do - for your employer on company time can raise nasty legal problems.  - In this situation, it's best to get a written release from your employer - in advance. -

-
-

- Place a copyright notice in all the important files you submit. Boost won't - accept libraries without clear copyright information. -

- -

- Guidelines -

-

- Please use these guidelines as a checklist for preparing the content a - library submission.  Not every guideline applies to every library, but - a reasonable effort to comply is expected. -

-

- Design and - Programming - -

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

- Directory - Structure and Filenames -

- - -
-

- Boost standard sub-directory names - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Sub-directory - - Contents - - - Required -
- build - - - Library build files such as a Jamfile. - - If any build files. -
- - doc - - Documentation (HTML) files. - - If several doc files. -
- example - - Sample program files. - - If several sample files. -
- src - - Source files which must be compiled to build the library.  - - If any source files. -
- test - - - Regression or other test programs or scripts. - - If several test files. -
-
-

- Redirection - -

-

- The primary directory should always contain a file named index.html (or - index.htm). Authors have requested this so that they can publish URL's in - the form http://www.boost.org/libs/lib-name with the assurance a - documentation reorganization won't invalidate the URL. Boost's internal - tools are also simplified by knowing that a library's documentation is - always reachable via the simplified URL. -

-

- If the documentation is in a doc sub-directory, the primary directory - index.html file should just do an automatic redirection to the doc - subdirectory: -

-
- - 
-<html>
-<head>
-<meta http-equiv="refresh" content="0; URL=doc/index.html">
-</head>
-<body>
-Automatic redirection failed, please go to
-<a href="doc/index.html">doc/index.html</a>
-
-</body>
-</html>
-
-
-

- Naming consistency -

-

- As library developers and users have gained experience with Boost, the - following consistent naming approach has come to be viewed as very helpful, - particularly for larger libraries that need their own header subdirectories - and namespaces. -

- -

- Here is how it works. The library is given a name that describes the - contents of the library. Cryptic abbreviations are strongly discouraged. - Following the practice of the C++ Standard Library, names are usually - singular rather than plural. For example, a library dealing with file - systems might chose the name "filesystem", but not "filesystems", "fs" or - "nicecode". -

- -

- When documenting Boost libraries, follow these conventions (see also the - following section of this document): -

- -

- Here are a few examples of how to apply these conventions: -

- -

- Documentation -

-

- Even the simplest library needs some documentation; the amount should be - proportional to the need.  The documentation should assume the readers - have a basic knowledge of C++, but are not necessarily experts. -

- -

- The format for documentation should be HTML, and should not require an - advanced browser or server-side extensions. Style sheets are acceptable. - ECMAScript/JavaScript is not acceptable. The documentation entry point - should always be a file named index.html or index.htm; see Redirection. -

-

- There is no single right way to do documentation. HTML documentation is - often organized quite differently from traditional printed documents. - Task-oriented styles differ from reference oriented styles. In the end, it - comes down to the question: Is the documentation sufficient for the - mythical "average" C++ programmer to use the library successfully? -

-

- Appropriate topics for documentation often include: -

- - -

- If you need more help with how to write documentation you can check out the - article on Writing Documentation for - Boost. -

- -

- Rationale -

-

- Rationale for some of the requirements and guidelines follows. -

-
-

- Exception-specification rationale -

- -

- Exception specifications [ISO 15.4] are sometimes coded to indicate what - exceptions may be thrown, or because the programmer hopes they will - improved performance.  But consider the following member from a smart - pointer: -

- 
-    T& operator*() const throw()  { return *ptr; }
-
-

- This function calls no other functions; it only manipulates fundamental - data types like pointers Therefore, no runtime behavior of the - exception-specification can ever be invoked.  The function is - completely exposed to the compiler; indeed it is declared inline Therefore, - a smart compiler can easily deduce that the functions are incapable of - throwing exceptions, and make the same optimizations it would have made - based on the empty exception-specification. A "dumb" compiler, however, may - make all kinds of pessimizations. -

- -

- For example, some compilers turn off inlining if there is an - exception-specification.  Some compilers add try/catch blocks. Such - pessimizations can be a performance disaster which makes the code unusable - in practical applications. -

-

- Although initially appealing, an exception-specification tends to have - consequences that require very careful thought to understand. The - biggest problem with exception-specifications is that programmers use them - as though they have the effect the programmer would like, instead of the - effect they actually have. -

-

- - A non-inline function is the one place a "throws nothing" - exception-specification may have some benefit with some compilers. -

-
-

- Naming conventions rationale -

-

- The C++ standard committee's Library Working Group discussed this issue in - detail, and over a long period of time. The discussion was repeated again - in early boost postings. A short summary: -

- - -
-

- - Source code fonts rationale -

-

- Dave Abrahams comments: An important purpose (I daresay the primary - purpose) of source code is communication: the documentation of intent. This - is a doubly important goal for boost, I think. Using a fixed-width font - allows us to communicate with more people, in more ways (diagrams are - possible) right there in the source. Code written for fixed-width fonts - using spaces will read reasonably well when viewed with a variable-width - font, and as far as I can tell every editor supporting variable-width fonts - also supports fixed width. I don't think the converse is true. -

-
-

- Tabs rationale -

- -

- Tabs are banned because of the practical problems caused by tabs in - multi-developer projects like Boost, rather than any dislike in principle. - See mailing list archives. Problems - include maintenance of a single source file by programmers using tabs and - programmers using spaces, and the difficulty of enforcing a consistent tab - policy other than just "no tabs". Discussions concluded that Boost files - should either all use tabs, or all use spaces, and thus the decision to - stick with spaces. -

-
-

- ECMAScript/JavaScript rationale -

- -

- Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript - documentation. Controversy followed (see mailing list archives), and the developers - were asked to remove the ECMAScript/JavaScript. Reasons given for banning - included: -

- -
-

- Rationale - rationale - -

-

- Rationale is defined as "The fundamental reasons for something; basis" by - the American Heritage Dictionary. -

-

- Beman Dawes comments:  Failure to supply contemporaneous rationale for - design decisions is a major defect in many software projects. Lack of - accurate rationale causes issues to be revisited endlessly, causes - maintenance bugs when a maintainer changes something without realizing it - was done a certain way for some purpose, and shortens the useful lifetime - of software. -

-

- Rationale is fairly easy to provide at the time decisions are made, but - very hard to accurately recover even a short time later. -

- -
-

- Acknowledgements - rationale -

-

- As a library matures, it almost always accumulates improvements suggested - to the authors by other boost members.  It is a part of the culture of - boost.org to acknowledge such contributions, identifying the person making - the suggestion.  Major contributions are usually acknowledged in the - documentation, while minor fixes are often mentioned in comments within the - code itself. -

- -
-

- Revised - - 04 November, 2003 -

-

- © Copyright Beman Dawes 2003. -

- -

- Distributed under the Boost Software License, Version 1.0. (See - accompanying file LICENSE_1_0.txt or copy - at www.boost.org/LICENSE_1_0.txt) -

- -