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

From: Peter Turcan (peterturcan_at_[hidden])
Date: 2024-02-20 03:42:38

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
>