| [/============================================================================== |
| Copyright (C) 2001-2010 Joel de Guzman |
| Copyright (C) 2001-2010 Hartmut Kaiser |
| |
| 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) |
| ===============================================================================/] |
| |
| [section Preface] |
| |
| [heading The Spirit Repository] |
| |
| The __spirit__ repository is a community effort collecting different reusable |
| components (primitives, directives, grammars, etc.) for __qi__ parsers and |
| __karma__ generators. All components in the repository have been peer reviewed |
| and/or discussed on the __spirit_list__. The aim is to broaden the scope of the |
| __spirit__ library while being able to maintain its high standards in terms of |
| code quality, flexibility, and maintainability. At the same time it encourages |
| people to contribute even small components as it lessens the hurdle of becoming |
| a __boost__ and __spirit__ author. |
| |
| Maintainability of the code and author commitment over a longer period of time |
| are crucial for /Spirit's/ success (as it is for the whole __boost__ project). |
| That allows the repository to play an additional role in terms of being a |
| proving ground for interested authors. It is a lot easier to remove code from |
| the repository than from the /Spirit/ core library. So if an author can't |
| maintain his/her contribution anymore for any reason, we are able to remove |
| those parts from the repository more easily. |
| |
| The repository is an excellent way of evolving things. The /Spirit/ core has |
| been developed for years, so we have a certain confidence of it being properly |
| designed and exposing a proven API. On the other hand, new ideas often need |
| some time to 'come to the point'. Changing API's is part of this business. At |
| the same time changing API's always mean user disruption, which we want to keep |
| to a minimum. Again, changing things in the repository is ought to be a lot |
| easier than in the core library. |
| |
| The quality of contributions is another key to success. That includes not only |
| the code itself, but takes into consideration such things as documentation, |
| tests, examples. The authors activity on the mailing list is related as well, |
| it's an important point. Only well supported things will evolve over time into |
| usable, high quality components. The mandatory discussions and the review of |
| contributions on the __spirit_list__ ensure the targeted high quality |
| standards. |
| |
| Based on the user feedback and general usability of things it it possible over |
| time to move repository components/grammars into the /Spirit/ core library. |
| |
| [heading How to use this manual] |
| |
| Some icons are used to mark certain topics indicative of their relevance. |
| These icons precede some text to indicate: |
| |
| [table Icons |
| |
| [[Icon] [Name] [Meaning]] |
| |
| [[__note__] [Note] [Generally useful information (an aside that |
| doesn't fit in the flow of the text)]] |
| |
| [[__tip__] [Tip] [Suggestion on how to do something |
| (especially something that not be obvious)]] |
| |
| [[__important__] [Important] [Important note on something to take |
| particular notice of]] |
| |
| [[__caution__] [Caution] [Take special care with this - it may |
| not be what you expect and may cause bad |
| results]] |
| |
| [[__danger__] [Danger] [This is likely to cause serious |
| trouble if ignored]] |
| ] |
| |
| This documentation is automatically generated by Boost QuickBook documentation |
| tool. QuickBook can be found in the __boost_tools__. |
| |
| [heading Support] |
| |
| Please direct all questions to Spirit's mailing list. You can subscribe to the |
| __spirit_list__. The mailing list has a searchable archive. A search link to |
| this archive is provided in __spirit__'s home page. You may also read and post |
| messages to the mailing list through __spirit_general__ (thanks to __gmane__). |
| The news group mirrors the mailing list. Here is a link to the archives: |
| __mlist_archive__. |
| |
| [endsect] [/ Preface] |
| |