1[/============================================================================== 2 Copyright (C) 2001-2011 Joel de Guzman 3 Copyright (C) 2001-2011 Hartmut Kaiser 4 5 Distributed under the Boost Software License, Version 1.0. (See accompanying 6 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7===============================================================================/] 8 9[section Preface] 10 11[heading The Spirit Repository] 12 13The __spirit__ repository is a community effort collecting different reusable 14components (primitives, directives, grammars, etc.) for __qi__ parsers and 15__karma__ generators. All components in the repository have been peer reviewed 16and/or discussed on the __spirit_list__. The aim is to broaden the scope of the 17__spirit__ library while being able to maintain its high standards in terms of 18code quality, flexibility, and maintainability. At the same time it encourages 19people to contribute even small components as it lessens the hurdle of becoming 20a __boost__ and __spirit__ author. 21 22Maintainability of the code and author commitment over a longer period of time 23are crucial for /Spirit's/ success (as it is for the whole __boost__ project). 24That allows the repository to play an additional role in terms of being a 25proving ground for interested authors. It is a lot easier to remove code from 26the repository than from the /Spirit/ core library. So if an author can't 27maintain his/her contribution anymore for any reason, we are able to remove 28those parts from the repository more easily. 29 30The repository is an excellent way of evolving things. The /Spirit/ core has 31been developed for years, so we have a certain confidence of it being properly 32designed and exposing a proven API. On the other hand, new ideas often need 33some time to 'come to the point'. Changing API's is part of this business. At 34the same time changing API's always mean user disruption, which we want to keep 35to a minimum. Again, changing things in the repository is ought to be a lot 36easier than in the core library. 37 38The quality of contributions is another key to success. That includes not only 39the code itself, but takes into consideration such things as documentation, 40tests, examples. The authors activity on the mailing list is related as well, 41it's an important point. Only well supported things will evolve over time into 42usable, high quality components. The mandatory discussions and the review of 43contributions on the __spirit_list__ ensure the targeted high quality 44standards. 45 46Based on the user feedback and general usability of things it is possible over 47time to move repository components/grammars into the /Spirit/ core library. 48 49[heading How to use this manual] 50 51Some icons are used to mark certain topics indicative of their relevance. 52These icons precede some text to indicate: 53 54[table Icons 55 56 [[Icon] [Name] [Meaning]] 57 58 [[__note__] [Note] [Generally useful information (an aside that 59 doesn't fit in the flow of the text)]] 60 61 [[__tip__] [Tip] [Suggestion on how to do something 62 (especially something that not be obvious)]] 63 64 [[__important__] [Important] [Important note on something to take 65 particular notice of]] 66 67 [[__caution__] [Caution] [Take special care with this - it may 68 not be what you expect and may cause bad 69 results]] 70 71 [[__danger__] [Danger] [This is likely to cause serious 72 trouble if ignored]] 73] 74 75This documentation is automatically generated by Boost QuickBook documentation 76tool. QuickBook can be found in the __boost_tools__. 77 78[heading Support] 79 80Please direct all questions to Spirit's mailing list. You can subscribe to the 81__spirit_list__. The mailing list has a searchable archive. A search link to 82this archive is provided in __spirit__'s home page. You may also read and post 83messages to the mailing list through __spirit_general__ (thanks to __gmane__). 84The news group mirrors the mailing list. Here is a link to the archives: 85__mlist_archive__. 86 87[endsect] [/ Preface] 88 89