> Can you suggest the organization that would work better for you?
1. In the beginning of Tutorial, start out with something like is shown on "Project Hiararchies" page - list all files, and their purposes in order to build minimal project; currently the first Hello, world chapter has no mention of project-root.jam, so the reader is unable to create a hello-world sample before he reads 4 more chapters.
2. Moving on from 1., list the purposes and functions different files in the hierarchy have; I'v used BB now for about a week, and I'm still confused between Jamfile, project-root.jam, site-config.jam, user-config.jam and custom .jam files, e.g. what can I do in each of them.
3. Then list target types (exe, lib, more?); the syntax for describing a target includes many fields (4 I think?), separated by :'s; describe each fields purpose, and add a complete list of values that can be placed in each field; for example, SOURCES field can also contain references to libraries, which wasn't intuitive at first.
4. Using the title "pre-built targets" isn't intuitivly refering to external libraries, I would suggest titling it as "Linking against external libraries".
5. Projects, why, how. Personally I'm still confused between project "requirements" and "usage-requirements"; I was unable to specify both. For example, I'm keeping Boost libraries sources in my code tree, so I have something like this: local BOOST_ROOT ; project boost
: requirements <include>$(BOOST_ROOT) <threading>multi <define>BOOST_ALL_DYN_LINK=1 :; lib boost_thread
: $(THREAD_SOURCES).cpp : <define>BOOST_THREAD_BUILD_DLL=1 : : <include>$(BOOST_ROOT) <threading>multi; As you notice, I had to use <include>$(BOOST_ROOT) twice, and I still haven't figured out why...
6. Command-line arguments full reference - currently all command-line arguments are spread across the manual. You go briefly over command-line args in Chapter 23, subsection "Command line" - but how does this fit under "Detailed Rerefence" heading?
... Adding custom command-line arguments. Requesting specific compilerversion from commandline (bjam gcc-4.0)? Requesting custom compile-command from commandline (bjam gcc="distcc g++-4.0" or bjam gcc="colorgcc") ? Setting variables from commandline (bjam sBOOST_ROOT=c:\boost - worked with BBv1, doesn't with BBv2 ?) ...
8. Variables, their usage; local, global variables; accessing variables cross Jamfiles (again from the above example, I'm unable to access BOOST_ROOT variable from anywhere else except the Jamfile that declared it, even with the 'local' keyword dropped from variale declaration).
- Document 'symlink' - Document --debug-configuration