search

boostorg / spirit

Boost.org spirit module
http://boost.org/libs/spirit
392 stars 161 forks source link

Extend README with info of Spirit libraries #357

Closed eyalroz closed 6 years ago

eyalroz commented 6 years ago

The Boost documentation for spirit (e.g. in Boost v1.66) gives the version as 2.5.x ; yet the master branch has a lot of files with x3 in their names. On the other hand, there are branches whose names begin with x3, suggesting it might not "really" be part of the main or development branch. If that's not all, there isn't a clear indication on other sites where one is supposed to find the X3 code.

I believe README.md should clarify this point.

Kojoley commented 6 years ago

@djowel can I delete x3-devel and x3-scalability branches? They does not have any commit that is not in the master branch.

djowel commented 6 years ago

@djowel can I delete x3-devel and x3-scalability branches? They does not have any commit that is not in the master branch.

Sure! Go ahead.

eyalroz commented 6 years ago

@Kojoley : So, closing the branches with X3 in their names reduces the confusion a bit, but the basic problem still remains:

Please consider adding a paragraph explaining the coexistence for X3 and non-X3 code.

Kojoley commented 6 years ago
  1. I do not know how often docs are rebuild and redeployed, I think every day, so just wait a little bit and they will appear at http://www.boost.org/doc/libs/develop/libs/spirit/doc/html/index.html.
  2. I do not know what you are wanting to say. All 3 version of Spirit are existing in Boost side by side and can be used. None of them are deprecated and planned for removal in near future. Boost libraries are reviewed before appearing in the release, so until something is not explicitly said to be experimental it is stable.
  3. And about v1 too, because it states Spirit is a set of C++ libraries for parsing and output generation. Most of people will not look for README.md of particular library in the Boost release distribution and it is not included in nix distros. Please consider opening a PR.
eyalroz commented 6 years ago

Let me try and explain. Think about this from the perspective of two users: One user who knows nothing about X3, and has just heard that "Spirit is a set of C++ libraries for parsing and output generation". The other has also heard that there might be some newer version of Spirit codenamed X3.

The first user arrives either at the official documentation on the Boost site, or arrives here on the GitHub repo (where s/he's essentially just forwarded there). This user will only know about Spirit 2.x since nobody tells him/her there might be another option.

The second user - if they see the official docs, they think "hmm, maybe X3 is only in development, or it's slated for a later release; let's check out the GitHub repo". Then they get here, and can still not understand whether they can, and whether they should, use X3.

Kojoley commented 6 years ago

No offence, but your imaginary user will give up on Spirit after a first compiler error message. If you have something to add and not satisfied with #362, please propose changes by writing a patch (open a PR).