Reece Dunn wrote:
4) Having a default.qbk automatically included. <<This is important for backward compatibility. The default.qbk contains the current highlighting schemes>>
Yes! Plus this allows us to easily add "built-in" support for new types. I would suggest something similar Boost Build, such as "bootstrap.qbk" for global setup and a "user.qbk" allowing additional site-specific tweaks without having to modify (and then merge at the next release) "bootstrap.qbk".
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.
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. 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]
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.
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... :)
- james
-- __________________________________________________________ James Fowler, Open Sea Consulting http://www.OpenSeaConsulting.com, Marietta, Georgia, USA Do C++ Right. http://www.OpenCpp.org, opening soon!
------------------------------------------------------- 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
