Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

X3: Top level documentation improvements #717

Open
Bockeman opened this issue Jan 26, 2022 · 1 comment
Open

X3: Top level documentation improvements #717

Bockeman opened this issue Jan 26, 2022 · 1 comment
Assignees

Comments

@Bockeman
Copy link

Under Boost Liraries "Spirit" and "Spirit Classic" are listed, but not distinguished.
It would be helpful if the latter indicated something like "a historical version, formerly Spirit 1.8".
There should be an entry for X3 with a user orientated distinction (even if only "for C++14 and later").
There's a "Spirit Repository" but this is 2.59, and nothing equivalent for X3.

There's now a link to X3 on the Spirit 2.59 page:
https://www.boost.org/doc/libs/develop/libs/spirit/doc/html/index.html
but it is well hidden, right at the bottom of the page.
But there's no reverse link to Spirit 2.59 on the X3 page
https://www.boost.org/doc/libs/develop/libs/spirit/doc/x3/html/index.html

The 2.59 Preface covers a History, but does not mention X3.
The X3 Preface does not show any history; this would be extremely useful.

Unlike 2.59, X3 does not contain a Rationale section.
The Rationale (or possibly History) should explain the differences between 2.59 and X3, and the reasoning behind the design choices.
It would be really helpful if this also contained something like "design objectives" like:

  • Intended to be simple and intuitive for casual users, but options available for the most sophisticated tasks.
  • Why X3 does not have the Qi,Karma,Lex equivalents.
  • Claims about performance and similar (really important for selling X3 and getting universal support).

Unlike 2.59, X3 does not contain a Notes section which might contain "Porting from 2.59".

The X3 index page
https://www.boost.org/doc/libs/develop/libs/spirit/doc/x3/html/index.html
contains a typographical error:

WARNING*: C++14 compilers support will be dropped soon.

should be corrected to

WARNING*: C++14 compiler support will be dropped soon.

In English, a noun-adjective (a noun used as an adjective) is always singular.

There's a dangling s forming the penultimate line.

@djowel djowel self-assigned this Jan 27, 2022
@djowel
Copy link
Collaborator

djowel commented Jan 27, 2022

It seems this is my task. Thanks for your comments! I'll find some time to work on this. Let's keep this open for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants