]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
13 | The __spirit__ repository is a community effort collecting different reusable | |
14 | components (primitives, directives, grammars, etc.) for __qi__ parsers and | |
15 | __karma__ generators. All components in the repository have been peer reviewed | |
16 | and/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 | |
18 | code quality, flexibility, and maintainability. At the same time it encourages | |
19 | people to contribute even small components as it lessens the hurdle of becoming | |
20 | a __boost__ and __spirit__ author. | |
21 | ||
22 | Maintainability of the code and author commitment over a longer period of time | |
23 | are crucial for /Spirit's/ success (as it is for the whole __boost__ project). | |
24 | That allows the repository to play an additional role in terms of being a | |
25 | proving ground for interested authors. It is a lot easier to remove code from | |
26 | the repository than from the /Spirit/ core library. So if an author can't | |
27 | maintain his/her contribution anymore for any reason, we are able to remove | |
28 | those parts from the repository more easily. | |
29 | ||
30 | The repository is an excellent way of evolving things. The /Spirit/ core has | |
31 | been developed for years, so we have a certain confidence of it being properly | |
32 | designed and exposing a proven API. On the other hand, new ideas often need | |
33 | some time to 'come to the point'. Changing API's is part of this business. At | |
34 | the same time changing API's always mean user disruption, which we want to keep | |
35 | to a minimum. Again, changing things in the repository is ought to be a lot | |
36 | easier than in the core library. | |
37 | ||
38 | The quality of contributions is another key to success. That includes not only | |
39 | the code itself, but takes into consideration such things as documentation, | |
40 | tests, examples. The authors activity on the mailing list is related as well, | |
41 | it's an important point. Only well supported things will evolve over time into | |
42 | usable, high quality components. The mandatory discussions and the review of | |
43 | contributions on the __spirit_list__ ensure the targeted high quality | |
44 | standards. | |
45 | ||
46 | Based on the user feedback and general usability of things it is possible over | |
47 | time to move repository components/grammars into the /Spirit/ core library. | |
48 | ||
49 | [heading How to use this manual] | |
50 | ||
51 | Some icons are used to mark certain topics indicative of their relevance. | |
52 | These 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 | ||
75 | This documentation is automatically generated by Boost QuickBook documentation | |
76 | tool. QuickBook can be found in the __boost_tools__. | |
77 | ||
78 | [heading Support] | |
79 | ||
80 | Please 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 | |
82 | this archive is provided in __spirit__'s home page. You may also read and post | |
83 | messages to the mailing list through __spirit_general__ (thanks to __gmane__). | |
84 | The news group mirrors the mailing list. Here is a link to the archives: | |
85 | __mlist_archive__. | |
86 | ||
87 | [endsect] [/ Preface] | |
88 |