Re: Ideas for documentation improvements

On Thu, Jul 18, 2019 at 11:36 AM Larry Evans <[email protected]>
wrote:

> On 7/18/19 9:19 AM, Maarten Verhage wrote:
> > 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.
> [snip]
> > 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.
> >
>
> The term "synthesized attribute" is well understood in attribute grammar
> circles.  Basically, the synthesized attribute of X is a function
> of the attributes of the children of X in the parse tree.
>
> At least that's what:
>
>   https://en.wikipedia.org/wiki/Attribute_grammar#Synthesized_attributes
>
> and that's how it's been described in many C.S. articles and books.
>

Agreed. Such is the learning curve in any highly conceptual domain. Why say
in a dozen or more words what can be said in two or three?

In general, I started glancing at the OP, and to be honest, got to a point
and wondered, what is the catch, what is the squeeze, and at a certain
point, TL;DR.

My chief feedback over the years is/was concerning floating point parser
support. I walked away from the docs with the distinct impression that
fixed point ought to be supported, however, in practice, found that not to
be the case. It's been a little while, but I think that's since been
addressed, but do not quote me on that. I've circled several wagons since
then and other than that, so I do not recall precisely.

It has also not been especially easy to drill into various aspects,
different sorts of attribute functions, that sort of thing. I'm not sure if
that is a function of the dependencies on libraries such as phoenix, etc.
Again, it's been a little while for me.

Other than that, if there is a specific question, I've found those
knowledgeable to be fairly responsive and with decent feedback where there
have been good questions.

Cheers.

_______________________________________________
> Spirit-general mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/spirit-general
>

_______________________________________________
Spirit-general mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/spirit-general