Ideas for documentation improvements

Dear Spirit mailing list members,

On the boost developers mailing list I wrote a message titled “Something off 
my chest about Boost” in which I shared my frustration about Boost library 
documentation. As well as some concrete suggestions. I admit the 
frustrations and suggestions where mainly for Spirit X3.

Among others I got a response from Michael Caisse who welcomed feedback from 
me and getting involved. I was really happy about that. As I believe I’m not 
a true beginner anymore I was thinking back when I first started with Qi and 
X3 to think of the things that where most confusing to me in the 
documentation to get started. So, yesterday I sat down thinking which 
suggestions where most effective for documentation improvements.

I sent this as a private email to Michael and Joel and from multiple sources 
I hear it is appreciated to make this public. Ok, that fine. So my first 
ideas are in this message.

Joel suggested me to open an “issue” on Github 
https://github.com/boostorg/spirit/issues , However when I look into 
existing issues people posted there I believe the audience is already on an 
advanced level about Spirit. Instead I can use some feedback on the 
suggestions that I share from other beginners with Spirit. Therefore I 
decided to post here on this mailing list. I believe when there is some 
agreement for documentation suggestions from multiple people it is more 
rewarding for the people rewriting documentation parts, because it is known 
to be helpful.

Ok, here I go:

A good example of frustration that people have when reading documentation is 
found in the following link:
https://stackoverflow.com/questions/13199027/is-there-any-clear-entry-level-documentation-available-for-boost-spirit

In order to combat this I think it is important to refer to tangible C++ 
terminology.
For example:

1) Parser synthesized attribute, is a vague term. To make it tangible you 
can say that the parser is internally working with adjusting iterator 
positions that attempts to match PEG expressions and when it finds a match 
it can call std::string( InputIt first, InputIt last ) for example. Then in 
the semantic action _attr( ctx ) is what we call an attribute. In this case 
a std::string.

2) Even so is rule synthesized attribute. Better is to say part of the 
datastructure where the parsed data needs to be assigned to. Maybe this is 
not true in a general sense but you give the readers something tangible.

Also I believe the tutorial examples are too much applications already. I 
believe it would be useful to show examples that demonstrates mere parser 
behavior.

For example:
1) Code example that has BOOST_SPIRIT_X3_DEBUG enabled. In it you can 
explain the structure of the xml language. Such as what is after <success> 
is the part of the input after the match.

2) Code example that demonstrates a little bit of the backtracking a parser 
does in its operation. Maybe in combination with 1. Pinpoint clearly to 
something that happens in the example as “this is what is called 
backtracking.”
3) Code example with a semantic action that prints the types of _attr( ctx ) 
and _val( ctx ). As an example for such a type printing feature please find 
my StackOverflow question: 
https://stackoverflow.com/questions/56819120/spirit-x3-how-to-get-attribute-type-to-match-rule-type, I 
call myself Zeyneb there. Anyway I think you will want something better than 
my goto stuff. You can also explain how something can go wrong if the types 
aren’t compatible. As well as pinpoint to something in the example of what 
is called an “attribute collapsing rule.”

Ok, let’s for now leave it with this. I’m curious what people have to say 
about this. I do have some more thoughts about mere additions in the Quick 
reference section but that’s something for later.

Best Regards,
Maarten Verhage