ceph/src/boost/libs/spirit/repository/doc/preface.qbk

   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