Re: Reminder: Review for Zach's parsing library starts on Feb 19th

From: Peter Turcan (peterturcan_at_[hidden])
Date: 2024-02-20 05:40:32

Marshall,

I should have mentioned my affiliation (technical writer) with C++
Alliance!

Apologies for the omission.

- Peter

On Mon, Feb 19, 2024 at 7:42 PM Peter Turcan <peterturcan_at_[hidden]>
wrote:

> Marshall,
>
> My 2c: Review of the Boost.Parser documentation.  I can see that
> considerable effort has been put into it so far, here are some ideas on how
> to improve it.
>
> Text - perhaps the text is a little small - consider a larger font size
> for both text and code examples. Refer to Microsoft MSDN for comparison.
>
> Introduction
> =========
> - Would be great to see a table with two columns. The first the Name of
> each parser included in the lib, the second a Description (a sentence or
> two) on the purpose of the parser. It is OK to have a table like this in an
> Introduction. The names can be linked into the Reference. Such a table
> encapsulates the full scope of the library in one spot, and tables are
> popular.
>
> - Would be nice to see some examples of scenarios or applications that
> would benefit from this library, or perhaps that this library is most
> targeted towards. For example, is Boost.Parser suitable for writing a
> language compiler or interpreter, data serialization (and deserialization),
> parsing config files, writing scripting engines, writing query languages,
> parsing high/low level protocols, natural language, mathematical
> expressions and formulae, or even text-based games or components of games
> (dialog?). This kind of introduction helps answer the "why" question - "Why
> should I be interested in this library?".
>
> - Perhaps give some ideas of "Combinatory Parsing" - some examples of
> parser combinations that work for any of the scenarios mentioned above.
>
> - Is some or all of the functionality available in the Standard Library,
> and if so, how does it compare?
>
> - Mention performance - what priority has this been given and are there
> any pertinent examples when compared with other options.
>
> Style points:
> ----------------
> - Avoid using words or phrases that add little or no meaning - such as
> "very" "simply" - sharpens the reading experience.
> - Avoid anthropomorphism - don't treat software as a human - software does
> not "know" about anything. It can record and reproduce - it never "knows"
> "likes" "dislikes" or similar
> - The introduction currently is over-technical, could use
> higher-level/conceptual treatment.
>
> Getting Started
> ============
> - Suggest having a "Getting Started with Boost.Parser" section, following
> the Introduction, even if the instructions are simple.
>
> - Include the B2 and CMake instructions to install the parser.
>
> - Include a section on Dependencies - even if the answer is "None".
>
> - Move the section on supported compilers/OS to this topic.
>
> Configuration and Optional Features
> ============================
> - Could do with some sub-headings for each Config option or Feature
> available.
> - Should follow the Getting Started section.
>
> Relationship to Boost.Spirit
> =====================
> - Consider moving this to or following the Introduction.
>
> Terminology
> ==========
> Good to have a terminology section, perhaps move this to following the
> "Configuration and Optional Features" topic as it doesn't seem to be
> specific to the Tutorials.
>
> Tutorial
> ======
> - Rename this to "Tutorials".
>
> - Many of the headings in this section are inactive labels (such as
> "Symbol Tables"). It is more compelling if these are active headings - for
> example: "Parse name/value pairs into Symbol Tables" - or whatever would be
> the active heading for this topic. And the same for all the other entries
> in the Tutorials section.
>
> - "Writing Your Own Parsers" is not as effective a heading as "Write Your
> Own Parsers".
>
> - Great to have this good range of tutorials.
>
> Concepts
> =======
> - Currently this is just a code block - add an introduction and explain
> what is being shown, and any nuances or potential sticky spots.
>
> Compiler Support
> ==============
> - Move to the Getting Started section, and add OS support (even if this is
> trivial - put it in writing).
>
> Reference
> ========
> - Great to have a full Reference though each entry needs textual
> explanation. For example, Macro BOOST_PARSER_USE_CONCEPTS, needs an
> explanation as to its purpose.
>
> - Add a "Description" heading and text to all Reference entries without
> one. Make sure any nuances, unexpected behavior, conflicts with other
> settings/macros/etc, special cases and the like, are mentioned in the
> Description.
>
> - Consider adding an "Errors and Exceptions" section to each Reference
> entry that might return an error, listing the errors/exceptions that might
> be returned or fired, and ideally what might have caused this and how to
> respond.
>
> - Remember tables are popular - tables of errors, parameters, fields,
> methods, etc.
>
> Navigation
> ========
> - Great to have all the code functions and structures mentioned in the
> Tutorials link to an entry in the Reference. It can work the other way too
> - adding an Example section to each reference, linking to one or more of
> the Tutorials (if an example exists).
>
> - Similarly for the Introduction and other front matter, if you are
> mentioning the name of a library component, make that mention a link.
>
>
>
>
>
>
>
>
>
> On Mon, Feb 12, 2024 at 8:04 AM Marshall Clow via Boost <
> boost_at_[hidden]> wrote:
>
>> That’s a week from now.
>>
>> Github: https://github.com/tzlaine/parser
>> Docs:   https://tzlaine.github.io/parser
>>
>>
>> — Marshall
>>
>>
>> _______________________________________________
>> Unsubscribe & other changes:
>> http://lists.boost.org/mailman/listinfo.cgi/boost
>>
>