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 Quick Start]
10
11[heading Spirit.Karma - what's that?]
12
13Throughout the description of __karma__ we will try to align ourselves very
14much with the documentation for __qi__. The reasons are many fold:
15
16* __karma__ is the counterpart to __qi__. Some people say it's the Yin to
17  __qi__'s Yang. __karma__ is generating byte sequences from internal data
18  structures as __qi__ is parsing byte sequences into those (very same) internal
19  data structures.
20* Both libraries have an almost identical structure, very similar semantics,
21  and are both built using identical tools. Both libraries implement a language
22  casting the specifics of their domain (parsing and generating) into a simple
23  interface.
24
25Why should you use a generator library for such a simple thing as output
26generation? Programmers have been using `printf`, `std::stream` formatting, or
27`boost::format` for quite some time. The answer is - yes, for simple output
28formatting tasks those familiar tools might be a quick solution. But experience
29shows: as soon as the formatting requirements are becoming more complex output
30generation is getting more and more challenging in terms of readability,
31maintainability, and flexibility of the code. Last, but not least, it turns out
32that code using __karma__ runs much faster than equivalent code using either
33of the 'straight' methods mentioned above (see here for some numbers:
34__sec_karma_numeric_performance__)
35
36You might argue that more complex tasks require more complex tools. But this
37turns out not to be the case! The whole Spirit library is designed to be simple
38to use, while being scalable from trivial to very complicated applications.
39
40In terms of development simplicity and ease in deployment, the same is true for
41__karma__ as has been described elsewhere in this documentation for __qi__: the
42entire library consists of only header files, with no libraries to link against
43or build. Just put the spirit distribution in your include path, compile and
44run. Code size? Very tight, essentially comparable to hand written code.
45
46The __karma__ tutorials are built in a walk through style, starting with
47elementary things growing step by step in complexity. And again: keep in mind
48output generation is the exact opposite of parsing. Everything you already
49learnt about parsing using __qi__ is applicable to generating formatted output
50using __karma__. All you have to do is to look at __karma__ as being a
51mirror image of __qi__.
52
53[endsect] [/Quick Start]
54