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
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@lists.boost.org> 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