On Wed, Jan 6, 2016 at 10:20 AM, Glen Fernandes wrote:

Rene wrote:

...

But at some point I, and possible others, will start making changes to all libraries to follow the requirements.

What about libraries with directories and files not listed in the requirements?

Still allowed. Although as you quoted me below, not something I personally would do (and something I need to fix in my own lib).

Other thread:

...

Having other dirs other than the required ones would not be common. And not something I would recommend.

Glen

-- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Wed, Jan 6, 2016 at 10:26 AM, Andrey Semashev wrote:

On 2016-01-06 19:02, Rene Rivera wrote:

...

Last Summer I brought up the subject of library organization requirements to make it easier to write the development and release tools needed to keep the Boost machine going. See this thread < http://lists.boost.org/Archives/boost/2015/06/223027.php> for a refresher.

This morning I committed the first part of the above.. A new set of library requirements that take into account existing practices. Adds some additional integration requirements. And puts in limits to reduce some integration burdens.

Please read the new requirements carefully < http://www.boost.org/development/requirements.html#Requirements>. It would be wonderful if authors start making changes as needed immediately. But at some point I, and possible others, will start making changes to all libraries to follow the requirements. So that the release, build, and testing teams can move forward with better support.

And of course, more cleanups and such will follow. Hopefully before the next release is out the door.

The page you linked says doc/html is required for all libraries. I hope you're not requiring to commit auto-generated docs to git?

I wasn't. I've now clarified what it means (as it applies to both pre-generated and generated docs). Also there's a typo:

1. Define a boostboost target.

I believe, it should be "boostbook".

Yep. Fixed it. Regarding the boostbook target, I'm not sure I understand what changes are

needed, if any. E.g. in my Jamfile I have:

xml log_doc : log.qbk : ... ;

boostbook log : log_doc : ... ;

Do I need to add:

alias boostbook : log : : : <implicit-dependency>log ;

or are the existing lines enough?

Yes, you need to add those lines. The intent is to eventually replace the hard coded lines in boost-root/doc/Jamfile.v2 with auto-discovered references to those alias targets.

The point of confusion for me is that there seems to exist the boostbook rule in Boost.Build and I'm supposed to re-define it with the alias?

It's not a redefinition as a rule is not in the same namespace as a target. But I see your point. And welcome alternative name suggestions for the target name :-) -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Wed, Jan 6, 2016 at 10:54 AM, Andrey Semashev wrote:

On 2016-01-06 19:39, Rene Rivera wrote:

...

On Wed, Jan 6, 2016 at 10:26 AM, Andrey Semashev < andrey.semashev@gmail.com> wrote:

...

Do I need to add:

alias boostbook : log : : : <implicit-dependency>log ;

or are the existing lines enough?

...

Yes, you need to add those lines. The intent is to eventually replace the hard coded lines in boost-root/doc/Jamfile.v2 with auto-discovered references to those alias targets.

Ok, thanks.

The point of confusion for me is that there seems to exist the boostbook

...

...

rule in Boost.Build and I'm supposed to re-define it with the alias?

It's not a redefinition as a rule is not in the same namespace as a target. But I see your point. And welcome alternative name suggestions for the target name :-)

Well, we could follow the standard target names from GNU:

https://www.gnu.org/prep/standards/html_node/Standard-Targets.html

The 'html' and 'pdf' target names look appropriate.

Not really appropriate.. As the same target is used to generate both HTML and PDF. And by that convention it should be "boostbook" as it's the target that generates BoostBook. Which by my own argument also says it shouldn't be "boostbook".. Oh the confusion ;-) -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Wed, Jan 6, 2016 at 11:04 AM, Andrey Semashev wrote:

On 2016-01-06 20:00, Rene Rivera wrote:

...

On Wed, Jan 6, 2016 at 10:54 AM, Andrey Semashev < andrey.semashev@gmail.com> wrote:

...

On 2016-01-06 19:39, Rene Rivera wrote:

And welcome alternative name suggestions for the

...

target name :-)

Well, we could follow the standard target names from GNU:

https://www.gnu.org/prep/standards/html_node/Standard-Targets.html

The 'html' and 'pdf' target names look appropriate.

Not really appropriate.. As the same target is used to generate both HTML and PDF. And by that convention it should be "boostbook" as it's the target that generates BoostBook. Which by my own argument also says it shouldn't be "boostbook".. Oh the confusion ;-)

Well, maybe 'doc' then? It is used in BOOST_ROOT/doc/Jamfile.v2 now.

Hm.. Might be confusing since it's the doc project (aka dir already). But perhaps "boostdoc" fits the use case? -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Wed, Jan 6, 2016 at 11:16 AM, Andrey Semashev wrote:

On 2016-01-06 20:06, Rene Rivera wrote:

...

On Wed, Jan 6, 2016 at 11:04 AM, Andrey Semashev < andrey.semashev@gmail.com> wrote:

On 2016-01-06 20:00, Rene Rivera wrote:

...

On Wed, Jan 6, 2016 at 10:54 AM, Andrey Semashev <

...

andrey.semashev@gmail.com> wrote:

On 2016-01-06 19:39, Rene Rivera wrote:

...

And welcome alternative name suggestions for the

...

target name :-)

Well, we could follow the standard target names from GNU:

https://www.gnu.org/prep/standards/html_node/Standard-Targets.html

The 'html' and 'pdf' target names look appropriate.

Not really appropriate.. As the same target is used to generate both HTML and PDF. And by that convention it should be "boostbook" as it's the target that generates BoostBook. Which by my own argument also says it shouldn't be "boostbook".. Oh the confusion ;-)

Well, maybe 'doc' then? It is used in BOOST_ROOT/doc/Jamfile.v2 now.

Hm.. Might be confusing since it's the doc project (aka dir already). But perhaps "boostdoc" fits the use case?

I'm ok with it.

OK, "boostdoc" it is. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Wed, Jan 6, 2016 at 12:25 PM, Louis Dionne wrote:

Rene Rivera writes:

...

[...]

Please read the new requirements carefully < http://www.boost.org/development/requirements.html#Requirements>. It

would

...

be wonderful if authors start making changes as needed immediately. But at some point I, and possible others, will start making changes to all libraries to follow the requirements. So that the release, build, and testing teams can move forward with better support.

[...]

When you write

The project must default to building standalone documentation if it has any.

What exactly is meant? Does it mean that running b2 with no arguments in $library/doc must generate the documentation (in the $library/doc/html folder)?

Yes, that's what it means. And hopefully that's already the convention for most. Is that a problem? -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On 2016-01-07 12:50, Artyom Beilis wrote:

...

f) javescript.

I thing the admonitions agains java script should be softened. Most of the concerns existent when the document was originally written don't apply to day. [snip] Robert Ramey

I'm second on that - no javascript requirement should be removed. One of the best source code documentation tools around generate javascript code to simplify navigation.

I'm talking of course about Doxygen :-)

To the reasons given in the rationale I can add that lots of people disable JavaScript in browsers (NoScript and similar tools), which would affect viewing the docs with it.

Robert Ramey writes:

A few observations

[...]

f) javescript.

I thing the admonitions agains java script should be softened. Most of the concerns existent when the document was originally written don't apply to day. I would like to see our html documentation support thinks like syntax coloring, running example code online, and the like. These things are often supported via injected javascript.

+1 I think JavaScript should be allowed, and even encouraged when it makes the documentation much superior. For example, Hana uses JavaScript to integrate performance benchmarks to the documentation in a nice way. Plus, all major browsers support JavaScript now, so I see this restriction as being outdated. Regards, Louis

...

Plus, all major browsers support JavaScript now, so I see this restriction as being outdated.

That might address one of the reasons given for banning it, namely:

- Incompatible with some older browsers and some text based browsers.

What's your take on the remaining ones?

- Makes printing docs pages difficult. - Often results in really bad user interface design. - "It's just annoying in general." - Would require Boost to test web pages for ECMAScript/JavaScript compliance. - Makes docs maintenance by other than the original developer more difficult.

Regards, -- Agustín K-ballo Bergé.- http://talesofcpp.fusionfenix.com

This is another reason why "banning" is bad, it is like banning exceptions in C++ is bad because some programmers do not aware of exception safety. Example: http://www.boost.org/doc/libs/1_60_0/libs/locale/doc/html/index.html It has very nice navigation bar that works very well and helps a lot in browsing. Yet if you disable JS you still get perfectly nice menus+navigation that work without any issues. See it isn't question of banning it is question of HOW to use JavaScript. If you take documentation sources in some kind of Json/XML or Markdown and convert it on the fly to some nice format with JavaScript to make it fancy yes it is bad. However if you use JavaScript to Enhance usability of the documentation it is very good. Some guys who really know about writing documentation (these behind Doxygen) generally know what to do very well. They do incorporate JavaScript because it good and enhances the user experience, If you ban it you just don't do justice to all people who's major project is actually creating tools for documentation. The fact that quick-book does not incorporate JavaScript isn't "good" it is just the way stuff is done. Bottom line instead of "Banning JavaScript" require the documentation to be printable and usable without it. Artyom

Agustín K-ballo Bergé writes:

On 1/7/2016 7:53 AM, Louis Dionne wrote:

[...]

That might address one of the reasons given for banning it, namely:

- Incompatible with some older browsers and some text based browsers.

Just like we drop support for old compilers when it's time to move on, perhaps it's time to do the same for documentation.

What's your take on the remaining ones?

- Makes printing docs pages difficult.

Printing documentation? Really? I didn't even know it was a use case, and I'd say change your workflow instead of changing the documentation.

- Often results in really bad user interface design.

This seems subjective. Plus, I'm not saying people should sprinkle JavaScript all over their docs when it's not needed and end up with a complicated mess. But some things are inherently dynamic, and JavaScript is currently the right way to do these things.

- "It's just annoying in general."

This, too, seems subjective. I've personally never been annoyed by JavaScript.

- Would require Boost to test web pages for ECMAScript/JavaScript compliance.

This seems like an academic argument. Sure, we could push things as far as to test that, but is it really an issue in practice? I don't think so. FWIW, I'd rather see proper CI being set up for the actual libraries than testing the documentation.

- Makes docs maintenance by other than the original developer more difficult.

Based on my current experience, I would say people are much more likely to contribute documentation fixes that change the content, not the build system or the way the documentation is laid out. In other words, most people submit PRs fixing the actual Doxygen comments, and they would never know that the documentation uses JavaScript anyway. So most contributors wouldn't be affected by JavaScript. Apart from that, it is true that JavaScript adds a layer of complexity on top of straight HTML, which could make maintenance slightly harder. Bottom line (IMO): Banning JavaScript from the Boost documentation is overkill, outdated, and not in line with existing practice. Instead, we should soften the ban to a simple warning like: JavaScript is OK, but don't get all crazy with it. Your documentation must still make sense when browsed with JavaScript disabled. Regards, Louis

On 07.01.2016 18:11, Robert Ramey wrote:

Useful applications of javascript that occur to me are:

b) syntax coloring for code examples

I disagree that this is a valid use of Javascript. Code examples are static, so they can and should be statically colored. This means that the syntax highlighting exists even if Javascript is disabled.

So I think the javascript admonition should be softened to say - "Documents should be readable with browsers which have javascript disabled" or something to that effect.

That's too soft for my taste, as it leaves open the possibility that the documentation without Javascript is unnecessarily feature-crippled (but still readable). I think that Javascript should only be used as a last resort, when there is no other way to provide the same functionality without Javascript. -- Rainer Deyke (rainerd@eldwood.com)

On 2016-01-08 12:40, Sam Kellett wrote:

On 8 January 2016 at 09:32, Rainer Deyke wrote:

...

On 07.01.2016 18:11, Robert Ramey wrote:

...

Useful applications of javascript that occur to me are:

b) syntax coloring for code examples

I disagree that this is a valid use of Javascript. Code examples are static, so they can and should be statically colored. This means that the syntax highlighting exists even if Javascript is disabled.

that's massively open to human error and adds a substantial workload on the dev which could be better spent (re)writing the actual documentation content to a better level.

Coloring is done automatically by QuickBook/BoostBook and doesn't require human intervention. I believe other source formats should also have this capability without involving JS. If you're writing plain HTML then yes, you would have to do this yourself, but that's just one of your problems as writing HTML is a pain in general. Probably, this is the reason why noone does this nowdays.

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Agustín K-ballo Bergé Sent: 07 January 2016 12:41 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..

On 1/7/2016 7:53 AM, Louis Dionne wrote:

...

Robert Ramey writes:

...

A few observations

[...]

f) javescript.

I thing the admonitions agains java script should be softened. Most of the concerns existent when the document was originally written don't apply to day. I would like to see our html documentation support thinks like syntax coloring, running example code online, and the like. These things are often supported via injected javascript.

+1

I think JavaScript should be allowed, and even encouraged when it makes the documentation much superior. For example, Hana uses JavaScript to integrate performance benchmarks to the documentation in a nice way.

I'm one of those that used to disable javascript by default. I wouldn't mind its use when it results in a superior documentation, as long as it's optional and I can still get at least a mediocre documentation with the basic information, and possibly some hint that I need to enable javascript for this site to see more (not just to navigate differently).

...

Plus, all major browsers support JavaScript now, so I see this restriction as being outdated.

That might address one of the reasons given for banning it, namely:

- Incompatible with some older browsers and some text based browsers.

What's your take on the remaining ones?

- Makes printing docs pages difficult. - Often results in really bad user interface design. - "It's just annoying in general." - Would require Boost to test web pages for ECMAScript/JavaScript compliance. - Makes docs maintenance by other than the original developer more difficult.

Isn't necessary? Paul PS In discussing documentation, we seem to be focussing only the 'printed page' documentation. Perhaps we should be looking forward to providing more 'documentation' that appears when using an IDE? You get this already to some extent with Visual Studio when hovering over a function or parameter name - the information about the function provided as a comment shows. This is much more helpful than reams of C++ reference documentation. To get this to work well, we need to have a *syntax* to the comments that could only show the relevant information, or a choice perhaps. The existing defecto standard of Doxygen, like \function a_function Does something Really Useful. \param thingys How many thingys to do something with. might serve this purpose. (At present, if you have a big Doxygen comment, you get everything, perhaps more than you want). Of course you still need tutorial-style examples with code snippets that will be web browsable.

On Wed, Jan 6, 2016 at 7:05 PM, Robert Ramey wrote:

A few observations

[cut] b) Organization. It's not clear whether or not files/directories besides

the one's listed are permitted. For example I have in the serialization library

/utility Jam scripts shared by other directories /performance Benchmark testing programs. Otherwise looks just like test /CMake CMake scripts to build the serialization library /doc/ html/ html documentation boostbook/ xml files to create html docs

May I presume that including these is not a problem? They don't conflict with any thing you've previously listed.

Still allowed. But.. I, as in personally, reorganize that to remove the extra top dirs :-) For example: /util * Move to /build/util /performance * Move to /test/performance /CMake * Move to /build/cmake /doc/boostbook * Rename to /doc/src But that's all just my personal preference. c) Building Documentation

I would need a better example to figure this out.

BTW one boost library should be selected as the "golden" or canonical example so that it can be used as an example for others to follow. Responsability for maintaining this is the "perfect" state would fall to the person responsable for keeping things running. The idea would be that someone complains that they can't figure this thing out (normally me), You can just point to the "golden example" and say do it this way.

I'm making my Predef library be that "golden" example. By commenting the source to illustrate the requirements. But since my lib doesn't have source it may not be the best. [cut] Basically, I'm impressed that this is a fairly conservative document which

doesn't require and major changes for anyone who has been trying to follow the rules all along.

We've always been careful to accommodate. As for the "[cut]" parts of your post.. I would suggest starting new threads for specific subjects (license, javascript, etc.). As I was only asking about the parts I changed in this. I.e. the structure/integration. Hope this helps make your job easier. Meh ;-) What would make it easier is doing PRs when there's consensus for other changes. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Glen Fernandes Sent: 07 January 2016 18:30 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..

Rene wrote:

...

I'm making my Predef library be that "golden" example. By commenting the source to illustrate the requirements. But since my lib doesn't have source it may not be the best.

It's interesting that Boost.Predef has both QBK sources and generated HTML output in the repository. I was considering doing this for Boost.Align but did not want repository history affected by commits around generation of documentation.

Now that we're on git, and each library's repository already has two branches (master,d develop), maybe it would be a good idea to institute (as policy) or support (in our infrastructure) a third branch for documentation.

Sounds a good idea to me, but let's see what John Maddock thinks too.

1. It serves the users who want to easily view documentation for a given library's repository. (They can clone that documentation branch).

If there are (and there should be) links to the include and examples folders, then these updated version are needed too.

2. It doesn't require us to put generated documentation output in our main development branches.

For cooperative working on Boost.Math, I found this very tiresome indeed. it made it impossible to see the wood for the trees.

3. It might even allow you support things like: "If <library> has 'docs' branch, don't require it to have a root level index.html."

It would allow anyone who wants 'developing' documentation updates to get them without having to build the toolchain to get an updated version - something that I've been kludging round by putting the built docs (and the other updated folders) on my personal Dropbox. I'd prefer to stop doing that. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

On Fri, Jan 8, 2016 at 4:35 AM, Raffi Enficiaud < raffi.enficiaud@mines-paris.org> wrote:

Le 07/01/16 19:30, Glen Fernandes a écrit :

...

Rene wrote:

...

I'm making my Predef library be that "golden" example. By commenting the source to illustrate the requirements. But since my lib doesn't have source it may not be the best.

It's interesting that Boost.Predef has both QBK sources and generated HTML output in the repository. I was considering doing this for Boost.Align but did not want repository history affected by commits around generation of documentation.

My 2cents...

I believe anything that can be generated automatically (and that is currently part of the release toolchain) should be deleted from the repositories.

See my previous reply as to why both are there for Predef.

Well... I still do not know what this index.html is for, so I am leaving it there :)

It's explained in the requirements doc we are discussing "Authors have requested this so that they can publish URL's in the form http://www.boost.org/libs/lib-name with the assurance a documentation reorganization won't invalidate the URL.".

One thing I would like to point concerning documentation is: - we have all the machinery on the develop and master branches to see the generated documentation: it is 0 effort from the developers to see the documentation as it would be shipped (no need to generate or commit/maintain generated file) - however the frequency of the updates is very low, sometimes once a month: I believe this should be done much more frequently, something like daily by one dedicated runner.

Part of the requirement changes is to do just that. As right now that machinery is complicated because of the toolchain setup and, in one case, hand written instructions to follow for building library docs. But do not despair, I'm working on it. And the current Travis-CI is set up to build docs for all libraries on every root update. This is part of supporting continuous building of release level archives. Unfortunately that currently has two problems: 1. It's failing to build ptr_container docs. See log < https://s3.amazonaws.com/archive.travis-ci.org/jobs/100985614/log.txt>. 2. We don't have a place to reliably upload non-master archives. Currently it's set up to upload to bintray.com on the master branch only. As doing the uploads on develop got us throttled for uploading too much. So if someone has a suggestion that is equivalent to bintray I would love to know about it. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Sat, Jan 9, 2016 at 8:23 AM, Raffi Enficiaud < raffi.enficiaud@mines-paris.org> wrote:

Le 08/01/16 17:39, Rene Rivera a écrit :

...

On Fri, Jan 8, 2016 at 4:35 AM, Raffi Enficiaud < raffi.enficiaud@mines-paris.org> wrote:

...

My 2cents...

I believe anything that can be generated automatically (and that is currently part of the release toolchain) should be deleted from the repositories.

See my previous reply as to why both are there for Predef.

Sorry, I cannot find the piece of information. While you (certainly) can

...

[snip]

...

One thing I would like to point concerning documentation is: - we have all the machinery on the develop and master branches to see

...

...

generated documentation: it is 0 effort from the developers to see the documentation as it would be shipped (no need to generate or commit/maintain generated file) - however the frequency of the updates is very low, sometimes once a month: I believe this should be done much more frequently, something

provide a good answer for predef, the question remains: would this practice of committing generated files be the recommended way? http://lists.boost.org/Archives/boost/2016/01/227127.php It goes something like this.. 1. A library is required to have HTML documentation. 2. A library *can* integrate into the global Boost documentation. 3. If a library doesn't do #2 it *must* provide prebuilt HTML documentation. Hence, even though Predef uses quickbook, it's never done #2. Therefore Predef does #3 :-) the like

...

...

daily by one dedicated runner.

Part of the requirement changes is to do just that. As right now that machinery is complicated because of the toolchain setup and, in one case, hand written instructions to follow for building library docs. But do not despair, I'm working on it. And the current Travis-CI is set up to build docs for all libraries on every root update. This is part of supporting continuous building of release level archives. Unfortunately that currently has two problems:

Well, you (I have the feeling that you support this burden alone... )

are facing a problem for maintaining the infrastructure. Wouldn't it be

or if developers want to do something fancy, they need to contribute to

OTOH, you are proposing a common interface for generating the different artifacts of the build (binaries, test results, doc...). If only one

...

1. It's failing to build ptr_container docs. See log < https://s3.amazonaws.com/archive.travis-ci.org/jobs/100985614/log.txt>.

The coupling here between libraries seems to be problematic as well (and also the coupling between doc, test, etc). To me, your are hitting the same

Not entirely alone. Daniel does most of the website and documentation support. And I do most of the automation and testing support. And a few other people, like John and Marshal, do other stuff. But we all overlap to some extent. the right time for restricting the toolset available to developers? Perhaps. But in the past that's been a considerable argument when that subject comes up :-) the generation toochain as well? As such, contributing to your travis.yml (or a Dockerfile for setting up the environment) would be beneficial. After all, code development, IT related stuff, etc, are all in the same boat. Indeed. library needs some special care and departs from that interface, I believe those commands can be integrated in the Jamfile directly with some black magic. The only thing that is impacted is the surrounding environment in which it is generated. Right. What I want is a single way that the tools can reliably build. And leave it up to authors to implement what they want from there. I.e. a build jamfile, and some specified results (html docs for example). Where that falls apart is on the requirements that the libs want for doing their builds. For example, for Geometry we need to download RapidXML to even build the custom documentation tool it uses, even before getting to use the regular quickbook/boostbook chain. problem as the discussions we already had concerning the regression tests (but this is obviously another topic).

...

2. We don't have a place to reliably upload non-master archives.

Currently

...

it's set up to upload to bintray.com on the master branch only. As doing the uploads on develop got us throttled for uploading too much. So if someone has a suggestion that is equivalent to bintray I would love to know about it.

I do not know bintray, it certainly does provide a lot of services. But I have the feeling that we "only" need a place to store files and make them available through a web server (along maybe with their revision, branch etc). I should be missing something in thinking that bintray is overkill.

It's convenient in the minimal setup on my end involved (just setting up the account and doing web POST requests). And the end result is reasonable.

We can continue this topic offline or in the test or build ML if you want.

Sure. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On 1/9/16 6:45 PM, Louis Dionne wrote:

Rene Rivera writes:

...

[...]

1. A library is required to have HTML documentation. 2. A library *can* integrate into the global Boost documentation. 3. If a library doesn't do #2 it *must* provide prebuilt HTML documentation.

Hence, even though Predef uses quickbook, it's never done #2. Therefore Predef does #3

Can't a library provide a Jamfile that generates the documentation, even if that documentation does not integrate with the global Boost documentation?

Many libraries do not "integrate with the "global Boost documentation"

It would be straightforward to require that doing `cd doc && b2` generates the documentation into `doc/html`, with index.html as an entry point.

You might think it would be straightforward - but it's not. The toolchain is long and finicky.

Committing pre-generated documentation is a big no-no, at least for me.

I'm aware that doing so is redundant. BUT it provides anyone who want's to browse boost just to do so directly, without building anything. For example, anyone can just start browsing the repo master branch without doing downloading or building anything. This is huge for new users of boost. The extra space used seems a small price to pay for this benefit. Robert Ramey

Robert Ramey wrote:

...

Committing pre-generated documentation is a big no-no, at least for me.

I'm aware that doing so is redundant. BUT it provides anyone who want's to browse boost just to do so directly, without building anything.

Yes. In addition, if we at some unspecified future point do switch to modular releases, it will be much easier to do them if the documentation for a library is included in its checkout.

Robert Ramey writes:

On 1/9/16 6:45 PM, Louis Dionne wrote:

...

Rene Rivera writes:

...

[...]

1. A library is required to have HTML documentation. 2. A library *can* integrate into the global Boost documentation. 3. If a library doesn't do #2 it *must* provide prebuilt HTML documentation.

Hence, even though Predef uses quickbook, it's never done #2. Therefore Predef does #3

Can't a library provide a Jamfile that generates the documentation, even if that documentation does not integrate with the global Boost documentation?

Many libraries do not "integrate with the "global Boost documentation"

...

It would be straightforward to require that doing `cd doc && b2` generates the documentation into `doc/html`, with index.html as an entry point.

You might think it would be straightforward - but it's not. The toolchain is long and finicky.

??? How is it more difficult to require `cd doc && b2` to generate the documentation rather than having it in place already? You already have to do `cd doc && b2` for libraries that integrate with the rest of Boost anyway.. There must be something I'm not getting.

...

Committing pre-generated documentation is a big no-no, at least for me.

I'm aware that doing so is redundant. BUT it provides anyone who want's to browse boost just to do so directly, without building anything. For example, anyone can just start browsing the repo master branch without doing downloading or building anything. This is huge for new users of boost.

People can browse the documentation online, which does not require any additional setup. I would posit that 95% of new users use the online documentation, and they don't use the offline documentation anyways. The way I see it, there should be a separate branch, say XYZ, which contains the documentation. This branch would simply need to be kept up to date with the documentation of every Boost library, which could be done by doing `cd doc && b2` in library's doc/ directory, and then copying the result to the right place. If someone wants to store the pre-generated documentation, this the Jamfile in `doc/` could just do nothing. Those wanting to get the offline documentation would simply need to clone the XYZ branch into a some directory, and then open it with their browser and everything would be in place. This would also remove the requirement for every library to have a index.html at its root, which is arguably weird. Note that this XYZ branch could also be kept as a submodule of the master repository, which wouldn't require any special action from users to get the offline documentation (besides git submodule update --init, which is already required).

The extra space used seems a small price to pay for this benefit.

It's not just about extra space. Source control is for _source_ files, not generated stuff. I don't want generated files to appear in the commit history of a code branch (but another branch like gh-pages is fine). All in all; I have no preference about exactly how this is handled, but if I have to track generated files in master or develop, then something is very wrong. Louis

On Sun, Jan 10, 2016 at 5:05 PM, Agustín K-ballo Bergé < kaballo86@hotmail.com> wrote:

On 1/10/2016 7:51 PM, Louis Dionne wrote:

...

Robert Ramey writes:

...

The extra space used seems a small price to pay for this benefit.

It's not just about extra space. Source control is for _source_ files, not generated stuff. I don't want generated files to appear in the commit history of a code branch (but another branch like gh-pages is fine).

By way of example, this is the kind of noise committing generated documentation can yield: https://github.com/boostorg/hana/commit/e471106dc850ad72f7abaf442b3570f7f34d...

And by comparison, here's the minimal non-noise that pre-generating for Predef has: < https://github.com/boostorg/predef/commit/009367d6a1b6a26199f5b849ea166c44cf...

.

-- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Sun, Jan 10, 2016 at 9:23 PM, Agustín K-ballo Bergé < kaballo86@hotmail.com> wrote:

On 1/10/2016 11:56 PM, Rene Rivera wrote:

...

On Sun, Jan 10, 2016 at 5:05 PM, Agustín K-ballo Bergé < kaballo86@hotmail.com> wrote:

On 1/10/2016 7:51 PM, Louis Dionne wrote:

...

Robert Ramey writes:

...

...

The extra space used seems a small price to pay for this benefit.

It's not just about extra space. Source control is for _source_ files, not generated stuff. I don't want generated files to appear in the commit history of a code branch (but another branch like gh-pages is fine).

By way of example, this is the kind of noise committing generated documentation can yield:

https://github.com/boostorg/hana/commit/e471106dc850ad72f7abaf442b3570f7f34d...

And by comparison, here's the minimal non-noise that pre-generating for Predef has: <

https://github.com/boostorg/predef/commit/009367d6a1b6a26199f5b849ea166c44cf...

...

.

I honestly don't get this... No source code appears to change, but the documentation somehow needs to be regenerated?

I changed predef.qbk, to document the new location of a tool.

Or does moving a .jam file to a different directory cause macros to become uppercase? Or is this commit a bunch of orthogonal changes bundled together?

Those macro changes where a result of a previous human error (the human being me.. really I'm human.. trust me). In that I forgot to regenerate the docs after merging a PR (it may have been laziness too). But the HTML changes are still minimal, and proportional to the doc/code changes.

Unless your documentation source is the HTML itself, committing documentation output will necessarily introduce noise as it modifies both the source and the target. But then we would be talking static documentation, not generated documentation.

Lost me on that. Don't know what you mean. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On 1/11/2016 12:23 AM, Agustín K-ballo Bergé wrote:

On 1/10/2016 11:56 PM, Rene Rivera wrote:

...

On Sun, Jan 10, 2016 at 5:05 PM, Agustín K-ballo Bergé < kaballo86@hotmail.com> wrote:

...

On 1/10/2016 7:51 PM, Louis Dionne wrote:

...

Robert Ramey writes:

...

The extra space used seems a small price to pay for this benefit.

It's not just about extra space. Source control is for _source_ files, not generated stuff. I don't want generated files to appear in the commit history of a code branch (but another branch like gh-pages is fine).

By way of example, this is the kind of noise committing generated documentation can yield: https://github.com/boostorg/hana/commit/e471106dc850ad72f7abaf442b3570f7f34d...

And by comparison, here's the minimal non-noise that pre-generating for Predef has: < https://github.com/boostorg/predef/commit/009367d6a1b6a26199f5b849ea166c44cf...

...

.

I honestly don't get this... No source code appears to change, but the documentation somehow needs to be regenerated? Or does moving a .jam file to a different directory cause macros to become uppercase? Or is this commit a bunch of orthogonal changes bundled together?

Unless your documentation source is the HTML itself, committing documentation output will necessarily introduce noise as it modifies both the source and the target. But then we would be talking static documentation, not generated documentation.

After digging a bit more I found that some of the changes relate to this commit https://github.com/boostorg/predef/commit/c4bebf10efa9322c732ffe27e3ea8e8ceb... dating from Dec 8, 2015 It's possible that the remaining documentation changes are too due to out-of-sync documentation. Regards, -- Agustín K-ballo Bergé.- http://talesofcpp.fusionfenix.com

On 1/11/2016 12:47 PM, Louis Dionne wrote:

Agustín K-ballo Bergé writes:

...

On 1/10/2016 7:51 PM, Louis Dionne wrote:

...

[...]

It's not just about extra space. Source control is for _source_ files, not generated stuff. I don't want generated files to appear in the commit history of a code branch (but another branch like gh-pages is fine).

By way of example, this is the kind of noise committing generated documentation can yield: https://github.com/boostorg/hana/commit/e471106dc850ad72f7abaf442b35

Just to make it clear; this is on the `gh-pages` branch of Hana, which is automatically updated by the CI script. I think Agustin's goal was to show how messy these commits can be, and why they should most likely not be mixed with usual code commits. Agustin, please correct me if I'm wrong here.

You are correct. In order to discuss Boost-wide policies one first has to understand how it could affect individual libraries. I'm under the impression that participants in this thread speak from their own libraries' point of view exclusively, when each tool has different costs and tradeoffs. Regards, -- Agustín K-ballo Bergé.- http://talesofcpp.fusionfenix.com

...

??? How is it more difficult to require `cd doc && b2` to generate the documentation rather than having it in place already? You already have to do `cd doc && b2` for libraries that integrate with the rest of Boost anyway.. There must be something I'm not getting.

The requirement is actually something like this:

1. Install all the requirements for what *all* the libraries want for building their docs.. CORRECTLY. 2. Run "cd doc && b2" for each library.

It's the CORRECTLY of #1 that the's "not easy" part. As it varies from system to system. And we don't have a requirement to limit the tools used. Although in reality it's a small number.. three (plus their dependencies): DocBook XSL, DocUtils, and RapidXML. And the last two are in use by a single handful of libraries.

+1 I just wanted to add small notes 1. I totally agree that requiring to build documentation to see one is just not an option. I used plain Doxygen in first place for Boost.Locale and will for other libraries just because setting up all the toolchain required too much effort and I'm susually working on Linux that makes stuff much simpler in terms of installation of multiple packages 2. I can agree that having pregenerated documentation in git is bad. I'd suggest to have some nightly doc build available on boost.org for each library master and develop. However I think more generation tools should be supported out of the box like plain Doxygen instead of quickbook.

So if those got replaced with something else that's "built-in", it would be easier.

Now this one is big "-1" Boost community already had reinvented 1001 tools just because they and they always think they know better and now we stuck with boost.build that I think vast majority of boost developers would be glad to get rid of. Now creating of documentation is very complex thing. Doxygen does it very well - not that it is trouble free - but it is de-facto industry standard and widely available. Maybe quick book can do some stuff nicer or better but I don't think it outweighs the maintainability requirements and ease for Boost.Developers. So... if you want to fix something please start use widely available and popular tools rather that reinventing yet another (...) that would make life of Boost.Developers even harder - just because you can. Do you want to make Quick Book better? Work with Doxygen developers community and integrate it into Doxygen toolchain. Artyom

Forgot to say.. On Sun, Jan 10, 2016 at 4:51 PM, Louis Dionne wrote:

People can browse the documentation online, which does not require any additional setup. I would posit that 95% of new users use the online documentation, and they don't use the offline documentation anyways.

That rationale has made me angry more times than I can count. I do a lot of my Boost work offline. In particular on the train to/from my day job. Specifically I mostly do test results web site work with Google App Engine. And it's infuriating that Google decided that no one works or reads docs offline. Even when faced with the repeated bug reports and feature requests to provide offline docs for GAE (and they aren't alone in the web dev realm in this behavior). I had to resort to web scraping their doc web site (with limited success). Just a data point though ;-) -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Raffi Enficiaud Sent: 11 January 2016 08:49 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..

Le 11/01/16 04:03, Rene Rivera a écrit :

...

Forgot to say..

On Sun, Jan 10, 2016 at 4:51 PM, Louis Dionne wrote:

...

People can browse the documentation online, which does not require any additional setup. I would posit that 95% of new users use the online documentation, and they don't use the offline documentation anyways.

That rationale has made me angry more times than I can count. I do a lot of my Boost work offline. In particular on the train to/from my day job. Specifically I mostly do test results web site work with Google App Engine. And it's infuriating that Google decided that no one works or reads docs offline. Even when faced with the repeated bug reports and feature requests to provide offline docs for GAE (and they aren't alone in the web dev realm in this behavior). I had to resort to web scraping their doc web site (with limited success).

Just a data point though ;-)

I also agree that having offline doc is a important thing: I can add that the navigation is much faster as well, and we can just grep things...

I like the idea of Andrey Semashev: distributing a separate archive for documentation and reducing the size of the distributed archive. For the PDF, I do not know exactly the use case, but I can image having one single file containing everything is something that is useful.

I use the PDF version regularly when updating Boost.Math - mainly to find things that I know are there (because I wrote them!) but can't find where. It's the find/search power that is the killer application. (And it is portable of course). And all this discussion focussing on the *look* of documentation is ignoring our main weakness - how to FIND what you want to know??? Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: 11 January 2016 15:03 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..

On 2016-01-11 17:42, Paul A. Bristow wrote:

...

I use the PDF version regularly when updating Boost.Math - mainly to find things that I know are there (because I wrote them!) but can't find where.

It's the find/search power that is the killer application. (And it is portable of course).

And all this discussion focussing on the *look* of documentation is ignoring our main weakness -

how to FIND what you want to know???

Personally, I never search for anything in html. This is just nearly useless because even if I find what I'm looking for the result is difficult to read (in a text viewer, which for me is mc in 99% of cases and far in the other 1%). That is assuming my search doesn't produce a lot of noise results due to

html

markup.

I've never seriously used pdf docs for Boost. I understand that it should be better in terms of noise results, but it just too inconvenient and heavy for me to use. Since most of the work I do is done from mc or a code editor like QtCreator, the pdf viewer feels like a fifth wheel (with a flat tire).

So, when I search for something, I search in either the source code or the docs sources. Which is why I like QuickBook - it is perfectly readable in the source form and doesn't clutter the content with

Why don't you have another window open? Preferably on another screen, of course. the

markup.

I'm surprised - but I can see that it makes some (a little) sense.

I'll emphasize that the above is written from the perspective of looking for something. When I want to learn something, i.e. read a considerable amount of text, possibly following links, I use html. It beats pdf as navigation is much easier.

Navigation *should* be as easy in PDF as HTML. It is if generated using Quickbook. All the links should be there (if a little less visible). Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: 11 January 2016 17:04 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..

On 1/11/16 8:36 AM, Paul A. Bristow wrote:

...

Navigation*should* be as easy in PDF as HTML. It is if generated using Quickbook. All the links should be there (if a little less visible).

It would be possible to make an xslt transform which would create a "navigator" from the BoostBook XML. To my mind, this would be very useful and very robust. In theory, it should be easy. In

practice

- not so much. I would love to see someone do this.

Another thing would be for library authors to invest the effort to understand and use boost autoindex. This would be the definitive solution to the "finding" problem. It works with the BoostBook XML so it would work across all renderings - pdf, html, epub - whatever. Unfortunately, it is one more hill to climb. On the other hand, it is very well documented and explained.

Sadly, despite implementing this for Boost.Math and others, I don't find that it is the definitive solution. It indexes all the class and functions etc automatically, and that's a good start, but relies on author input to the index.idx file to add other search terms. And even then, if you don't have the same expectation as to the name of something as the author, then you still won't find it. Eating my own dogfood, as it were, to find things in Boost.Math, I don't find it as good as I had hoped. I find that I too often end up doing a global search of the PDF. And the index can become massive and slow to scroll and scan. But it's one more weapon... Paul

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: 11 January 2016 17:27 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..

On 2016-01-11 19:36, Paul A. Bristow wrote:

...

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: 11 January 2016 15:03 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..

I've never seriously used pdf docs for Boost. I understand that it should be better in terms of noise results, but it just too inconvenient and heavy for me to use. Since most of the work I do is done from mc or a code editor like QtCreator, the pdf viewer feels like a fifth wheel (with a flat tire).

Why don't you have another window open? Preferably on another screen, of course.

I find it inconvenient to switch back and forth between windows all the time.

And I have only one screen.

Big mistake!

...

Navigation *should* be as easy in PDF as HTML. It is if generated using Quickbook. All the links should be there (if a little less visible).

PDF viewers typically don't have Back/Forward/Open in a new tab buttons, which I extensively use while browsing.

Most annoyingly on recent Adobe Readers, they are hidden by default, but still exist. (Microsoft Edge is only suitable for reading web-trash). :-( Paul

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Agustín K-ballo Bergé Sent: 11 January 2016 16:14 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..

On 1/10/2016 3:10 AM, Robert Ramey wrote:

...

On 1/9/16 6:45 PM, Louis Dionne wrote:

...

Committing pre-generated documentation is a big no-no, at least for me.

I'm aware that doing so is redundant. BUT it provides anyone who want's to browse boost just to do so directly, without building anything. For example, anyone can just start browsing the repo master branch without doing downloading or building anything. This is huge for new users of boost. The extra space used seems a small price to pay for this benefit.

I would expect new users of Boost to pick a release, which does come with generated HTML documentation, not to randomly clone a repository in an unknown status.

We should not forget prospective libraries under development, being tried out, and under review. (They need to have links to existing libraries too). Paul

On 1/7/16 10:21 AM, Rene Rivera wrote:

On Wed, Jan 6, 2016 at 7:05 PM, Robert Ramey wrote:

...

A few observations

[cut]

Still allowed. But.. I, as in personally, reorganize that to remove the extra top dirs :-)

For example:

/util * Move to /build/util /performance * Move to /test/performance /CMake * Move to /build/cmake /doc/boostbook * Rename to /doc/src

But that's all just my personal preference.

Hmmm- I took pains to be sure that I didn't conflict with any of your stuff. That's why I didn't want to put anything into your directories. I still think that's a good idea. doc/src ... Hmmm - some people use markdown, etc. It's unclear to me whether you're going to specify that it be a requirement that there be a bjam file if and only if boost book is used. Or maybe you want to try to require that every doc/src include a jamfile to produce the html in accordance with the contents of doc/src. Personally, I'm ok if you want to mandate doc/src and a jamfile if possible. But I doubt it would be popular.

[cut]

Basically, I'm impressed that this is a fairly conservative document which

...

doesn't require and major changes for anyone who has been trying to follow the rules all along.

We've always been careful to accommodate.

Actually, I think you've been too accomodating. I think you'd be better off making sure you have the absolute minimum requirements you can live with - but then insisting on these being respected. Easier said than done I know.

As for the "[cut]" parts of your post.. I would suggest starting new threads for specific subjects (license, javascript, etc.). As I was only asking about the parts I changed in this. I.e. the structure/integration.

LOL - I just followed the link to the whole page. I didn't know which parts you changed.

On 1/9/2016 5:01 PM, Soul Studios wrote:

I would also like to see guidelines for the use of small custom macros in boost libraries.

I don't mean the use of already-defined compiler-feature macros like BOOST_NOEXCEPT etc, I mean defining small macros for the sole purposes of a single library.

By far the best solution regarding macros in a Boost library is that every macro for library 'xxx' start with the prefix of BOOST_'XXX'_ etc. Both the Boost PP and Boost VMD macro libraries use this technique and I see no reason why it can't be extended to all other Boost libraries. I understand many developers like the brevity of shorter macro names but the chance for macro clashes with other code, as well as the chance for macro clashes with specifically other Boost library code, increases drastically when this technique is not used. I do understand that Boost.config macros do not use the above technique but Boost.confifg being such a special case and so central to all other Boost libraries, it can be forgiven for its BOOST_'XXX' brevity.

I have a number of situations in a prospective library where small macro #defines (#undef'ing at the end of the header) which change their definition based on the availability of specific compiler features (allocator traits, for example), are the most elegant solution- for various reasons but largely because the alternatives are either a lot of "#ifdef COMPILER_FEATURE"-type code replication, or single-line template-based inline functions which will (a) slow compilation time, (b) not be correctly optimised or inlined by most microsoft compilers, and (c) make for ugly code (subjective, but there it is).

I can't find anything in your documentation, so I just thought I'd ask if there are any definitive guidelines around the use of small macros in boost libraries. If so can they be included- Cheers, Matt

On Sat, Jan 9, 2016 at 11:33 PM, Soul Studios wrote:

Thanks Glen and Edward, those suggestions make sense. Rene, if that information could be put in the guidelines it would be useful.

PRs welcomed ;-) -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Sun, Jan 10, 2016 at 4:44 PM, Soul Studios wrote:

Thanks Glen and Edward,

...

...

those suggestions make sense. Rene, if that information could be put in the guidelines it would be useful.

PRs welcomed ;-)

My impression was that you were asking for feedback and suggestions for changes- at any rate, where's the repo?

I was asking, pointing out, about the structure and integration parts. Everything is always up for changes if the community agrees. Here's the github doc < https://github.com/boostorg/website/blob/master/development/requirements.htm...

.

-- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

On Sat, Jan 9, 2016 at 5:01 PM, Soul Studios wrote:

I would also like to see guidelines for the use of small custom macros in boost libraries. [cut] I can't find anything in your documentation, so I just thought I'd ask if there are any definitive guidelines around the use of small macros in boost libraries.

If there are macros in your public headers that are defined but always undefined, then it won't impact users of your library. If the macros are not undefined: 1. Make sure they are documented so that users know about them 2. Make sure the macro namess are prefixed with the library name For example, for Boost.Something, in boost/something/file.hpp: #ifndef BOOST_LIBRARY_SOMETHING_FILE_HPP #define BOOST_LIBRARY_SOMETHING_FILE_HPP // ... #if defined(__INTEL_COMPILER) #define BOOST_SOMETHING_USING_ICC #endif // ... #if !defined(BOOST_NO_CXX11_ALLOCATOR) #define SHOULD_USE_ALLOCATOR_TRAITS #endif // ... #undef SHOULD_USE_ALLOCATOR_TRAITS // ... #endif Of course, include guard macros fall into the second category, but it's fine if you do not document them. (And it wouldn't be a bad idea for macros in the first category to also be prefixed with the library name). Glen

On Sun, Jan 10, 2016 at 5:12 AM, Rainer Deyke wrote:

#define SHOULD_USE_ALLOCATOR_TRAITS #include

#ifndef SHOULD_USE_ALLOCATOR_TRAITS #error Where did my macro go? #endif

Good point; even more motivation for:

(And it wouldn't be a bad idea for macros in the first category to also be prefixed with the library name).

And use BOOST_SOMETHING_SHOULD_USE_ALLOCATOR_TRAITS even if it is undefined. Glen