Reece Dunn wrote:
I don't think you need something similar to BoostBuild. The reason is that BoostBuild has a different mechanism to scan for jam files. By providing the following rules for locating a qbk file (in the order the directories are searched):
1. Search the path of the current qbk file being processed;
2. Search the paths specified from the command line;
3. Search a default directory (where default.qbk is located).
That sounds good to me. I wasn't thinking that QuickBook needed anything near the complexity of BoostBuild in trying to find qbk files - yikes! What I am suggesting is that in addition to whatever files are explicitly requested via [include ...], there should always be two files loaded automatically prior to processing the main qbk file. One should be for implementation of "built-in" features (such as C++ & Python syntax highlighting, if that gets converted to the dynamic format), and one should be for user specified "global" features. That is all I was suggesting we copy from BoostBuild.
That makes sense.
This would then allow you to provide a default.qbk in either the current search path or one of the paths from the command line, thus overriding the default behaviour.
It may also be advisable to allow environment variables in the include path, allowing
-- default.qbk
[include (QUICKBOOK_ROOT)/default.qbk] # import default qbk behaviour
[include syntaxes/java.qbk] # add Java syntax highlighting
Alternatively, you could add quickbook_root and boost_root as predefined values. I can't remember the exact QuickBook syntax, but it would behave like a def statement:
[def boost_root $(BOOST_ROOT)]
[def quickbook_root $(boost_root)/tools/quickbook]
This would have the advantages of: 1. fitting in with the existing quickbook preprocessing mechanism; 2. allow you to use other def aliases in an include statement; 3. not require special environment variable handling and support.
I like the concepts, although the examples would look different if we have default.qbk/user.qbk automatically loaded, and QUICKBOOK_ROOT/BOOST_ROOT automatically in the search path.
The example above was an attempt to show how to override the preset default.qbk by providing one in one of the earlier search paths and how you might go about importing the default one (because [import default.qbk] would be recursive otherwise). The underlying idea was to show that it is possible to just have the one auto-included file (default.qbk) and that you can provide your user.qbk functionality by providing a custom default.qbk in a search path you specified in the command line or where the top-level qbk file is located.
In C/C++, an analogous thing would be providing your own <utility> header and overriding the one in your preferred standard library implementation and then including the utility header from that standard library implementation. (I am not saying that this is good practice, just that it is possible. However, on that note, if the TR1 extensions extend <functional> for example, this might be a valid technique to add the TR1 behaviours.)
Someone's global "user.qbk" file might look like:
[def ACE_DOCS_DIR $(ACE_ROOT)/docs] # get root directory of ACE framework from environment
[include syntaxes/java.qbk] # add experimental Java syntax highlighting, test and
# move to defaults.qbk for next release
with a specific project's qbk docs containing
[library virtual_messaging ...] [include highlights_for_my_mini_ACE_frontend_grammar.qbk] # ... [section.ace_hints Tips on Using Ace and Boost Together] # define ACE_DOCS_DIR for your configuration in user.qbk [include $(ACE_DOCS_DIR)/ace_hints_for_boost_users.qbk] [endsect]
You could do a similar thing using my mechanism.
In general, I think we should try and minimize the explicit use of [include ...] in "end user" project qbks importing files outside of the local directory. I agree with having a search path with a common central location, but it might be better for the long term clarity and maintainability of QuickBook based docs if such lookups are rarely necessary. We can do all kinds of cool and complicated things within the autoloaded "default.qbk" and "user.qbk", because the author who just wants to document part of his library doesn't have to know how that works, keeping the actual qbk(s) for their project as clean and simple as possible.
I agree. This is one reason for having the search paths on the command line. The situation where this becomes an issue is where you have the same file in path a and path b, the program selects the file from path a but you then (in the path a version) want to include the file from path b. In this instance, you *need* to be explicit in order to prevent recursion. Allowing the use of defs simplifies the process, especially if you move path b to a new location.
This also allows you to do something like:
[def neatstuff java.qbk] ... [include syntaxes/$(neatstuff)]
A more useful thing would be:
[def projectdir mydocs]
[include $(projectdir)/introduction.qbk] [include $(projectdir)/tutorial.qbk] [include $(projectdir)/references.qbk]
This was a braindead moment on my part! Ignore the colour specification element of my suggestion. Of course CSS is definitely the way to do specify the styling.
Nah, you were on too much of a roll to be braindead. Momentarily distracted perhaps, but methinks your brain is plenty healthy... :)
:)
Regards, Reece
------------------------------------------------------- SF email is sponsored by - The IT Product Guide Read honest & candid reviews on hundreds of IT Products from real users. Discover which products truly live up to the hype. Start reading now. http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
