On Sat, Apr 6, 2019 at 11:23 PM Robert Ramey via Boost < boost@lists.boost.org> wrote:
On 4/6/19 7:22 PM, Rene Rivera via Boost wrote:
These are not options pertaining to B2 itself. And hence have no mention
in
the B2 documentation. You can see the options by doing:
$ cd boost-root $ b2 --help
There are numerous install and build directory options listed in that. Use the appropriate one. For the tagging there's a concept of "buildid" for which there are two options present. The appropriate place to document these in addition to the "--help" printout would be in the Getting Started Boost pagesOr perhaps some other "Building Boost" documentation. Or optionally the wiki. And it would seem that such "Case Study" examples would lend themselves well to having on the wiki. Especially since it's really, really, really, easy for everyone to contribute such documentation through direct edit suggestion PRs to the wiki.
I think this view is very typical of library and tool developers. And I think it's a big problem.
TL;DR: You injected way more meaning into what I said. To the point of mischaracterizing my intentions of simple declarative information. a) Technically you're correct in that all the required information is
available if one is willing to dig deep enough and invest some time. I think the time required is more than you think it is though.
Yes, I gave technical declarative information. I don't understand how you ascertained anything past my technical statement.
b) You frame task is building the software and the job of "spoon feeding" the user as beyond the developers responsibility and perhaps his ability.
I fixed the spelling mistake in that for you ;-) c) I think you're dead wrong on this. Your task, should you choose to
accept it, is to create something that lots of people will use and will spread.
Yes, what I chose to create was "Boost Build" and "Boost Predef".
d) So, if the task isn't accomplished, the developer isn't done. He's failed to complete the required task.
Correct, I'm not done. e) So this means putting the document on par with the code. The code
programs the machine, and the document programs the user. If one doesn't work - nothing works.
Yep, I continually work on documentation improvements. For example spending a year converting Boost Build documentation to a format that was a magnitude easier for myself and others to contribute to. Which has worked splendidly as we've gotten a handful of outside contributions in both general improvement and new features with accompanying documentation. f) Defining the task in this way and approaching it accordingly will
result in a work flow which shuttles bank and forth between code and document resulting in better and simpler versions of both. This is because when problems are discovered, we can fix it in the simplest place to fix it.
Right. Which is why Boost Build and Boost Predef Documentation is partially embedded in the source code and is in a simple text format. As it makes it's more likely to get updated and be accurate. And that has been proven to work rather well as experience with it has shown. I know you guys are tired of me preaching this repeatedly. I'm sorry
about this.
I'm not tired of that. But let me clarify my original statement.. The installation and buildid features of "Boost C++ Libraries" are not part of "Boost Build" (B2). B2 implements a build system that provides supporting mechanisms to those features but does not contain them itself. They are properly features of "Boost C++ Libraries" only. As a concrete delineation of that consider this github search < https://github.com/search?q=org%3Aboostorg+buildid&type=Code> for "buildid" in the entirety of all the Boost libraries. You can observe that the places where that is present are in the super-project and in Boost.Config. Hence _not_ in Boost Build. As such, my original key point, that such documentation belongs where it currently is. And perhaps, and almost certainly, as additions to the "Getting Started" documentation. But also that it could be added in the wiki where it is more amenable public contribution. I did not at any time say that such documentation should not be written. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net