[Boost-build] user-config.jam - suggested helpful comments for this file.

From: Paul A Bristow (pbristow_at_[hidden])
Date: 2006-09-21 12:50:46

Four things caused me some grief configuring user-config.jam on Windows:

1 Anyone putting files into a Windows file/directory with spaces
(allowing spaces must be one of the silliest ideas since arrays without
lengths)

like C:/program files/... will find (perhaps eventually!)

"C:/Program Files/DocBookXSL/docbook_xsl_1_70_1" doesn't work
it MUST be a DOS-style name, for example:

using boostbook
: C:/Progra~1/DocBookXSL/docbook_xsl_1_70_1
: C:/Progra~1/DocbookXML/42
;

2  It would seem that one needs to use forward / slashes, not backward \
ones. Worth a comment note.

3  In view of bjam's unusual spaces_are_delimiters syntax, mistakes could be
reduced by adding a 'skull-and-crossbones' reminder warning comment IN THE
SAMPLE FILE itself.

Using the bizarre layout also helps avoid this pit.
For example:

# WARNING COMMENT: jam files use an unusual spaces_are_delimiters syntax.
# Leave a space or newline before and after every item, even keywords, 
# including before and after any punctuation like : or ; 

4  It would be helpful to recommend keeping the reference template version
in the Boost directory,
but suggesting at least placing a customised version in (say)

c:\documents and settings\administrator

and/or a link to the instructions proper:

http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/bbv2/referen
ce.html

HTH

Paul
---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]