[DOC] improve description of CPPDEFINES

[mwichmann]

The CPPDEFINES entry and the Append method entry has some additional clarification added, about ways cpp macros can be specified. Added a couple more examples to illustrate.

Doc-only change.

Signed-off-by: Mats Wichmann [email protected]

Contributor Checklist:

• [ ] I have created a new test or updated the unit tests to cover the new/changed functionality.
• [X] I have updated CHANGES.txt (and read the README.rst)
• [X] I have updated the appropriate documentation

[mwichmann]

As part of this work, I added another example, intending to show the use of a (list, tuple) of tuples and/or a dictionary to pass multiple values to CPPDEFINES. This blows up the doc build, with an unhelpful error (the message is "string", it's something in lxml). Since we're not worse off by doing so - the example was not included before - I've commented it out in the latest commit, maybe can revisit some time to try to find out why this kills it.

[jcbrill]

@mwichmann When working on #4174, I ran into docbook issues that were related to a internal lxml global limit that resulted in docbook failures without particularly helpful messages. The root cause took more time that it should have to figure out what was going awry.

That particular issue was solved by added the ability to increase the global limit and hard-coding a new constant.

As part of #4174, the following snippet was added to SCons\Tool\docbook\__init__.py:

#
# lxml etree XSLT global max traversal depth
#

lmxl_xslt_global_max_depth = 3100

if has_lxml and lmxl_xslt_global_max_depth:
    def __lxml_xslt_set_global_max_depth(max_depth):
        from lxml import etree
        etree.XSLT.set_global_max_depth(max_depth)
    __lxml_xslt_set_global_max_depth(lmxl_xslt_global_max_depth)

At the time, the hard-coded constant 3100 was larger than what was necessary to build the documentation. Perhaps not so anymore.

Could be worth a try to bump up the global max depth to see if that is the problem. For all I know, there may be more limits hard-coded into lxml as well.

EDIT ADDITION:

https://lxml.de/api/lxml.etree.XSLT-class.html

set_global_max_depth(max_depth)
Static Method

The maximum traversal depth that the stylesheet engine will allow. This does not only count the template recursion
depth but also takes the number of variables/parameters into account. The required setting for a run depends on
both the stylesheet and the input data.

Example:

XSLT.set_global_max_depth(5000)
Note that this is currently a global, module-wide setting because libxslt does not support it at a per-stylesheet
level.

[mwichmann]

Thanks! I remember reading about this in your PR now you mention it, and it clearly didn't sink in because I in no way made the connection. Your guess is probably on target - bumping the limit made one build work out, but then something else blew up (in Sphinx, so it's past the phase where lxml is involved).

[mwichmann]

Closed in favor of #4263