Hi James,
Wow. I wish I was as eloquent as you are. Pardon me if my reply will not be as detailed as yours.
I agree. It was an interesting read.
There are a few different parts here, which I didn't really clarify. One is the concept of adding a new QuickBook command to explicitly load a syntax definition. The second is all the interesting "extras" which could eventually build on the first. Taken as a whole, perhaps that is a bit fancy, but perhaps the basic idea of explicitly loading a syntax definition, without doing all those extras, qualifies as starting simple?Why at startup? Why not actually load (include) dynamic syntax definitions explicitly, something like "[sourcemode foo]" pulling in "*/foo/.highlight_def_extension*"? This could look first in the local directory, then search relative to a some standard lookup path (perhaps $BOOST/tools/QuickBook/highlighters ?). It might allow for more intelligent feedback on errors (i.e., dependency on a definition file that isn't found). I think it could even be leveraged to allow BBv2 to treat referenced definitions as dependencies, triggering a QuickBook "rebuild" if the definition is updated (which might be much harder to do otherwise, short of any change to any definition file triggering every .qbk to get reprocessed whether or not it used that definition).
Too fancy, I think. But you do have a point. Maybe we can start simple and build our way there.
The third part, which is perhaps the most important, I realize I simply assumed without saying anything. What is the intended visibility of these syntax definitions? If it's only those working on QuickBook itself, as an easier way to provide built-in syntax highlight parsing, then this is an interesting implementation detail but ultimately of little significance beyond QuickBook developers. However, if the idea is (and here's where I might have jumped to an assumption) that the ability to create custom grammars would be exposed and provided to QuickBook users writing documentation using QuickBook (but not necessarily involved in QuickBook development), then this directly impacts the "interface" QuickBook provides to it's users.
There are several ways in which I can envision productive uses for "project local" syntax highlighting definitions. For example, it would be pretty neat to have syntax highlighting for QuickBook's own syntax in the QuickBook documentation, but there wouldn't be much use for that format outside of quickbook.qbk. For this to work, there needs to be a very clear, reliable mechanism for a project to express such customizations in a way which future improvements to QuickBook can easily avoid breaking. The idea of adding an explicit command to QuickBook for loading custom syntax highlighting definitions was based on this idea of projects being able to create their own, local definitions, not for built-in formatting definitions which may happen to be implemented by a dynamic definition file. Having a tool like QuickBook implicitly find such local, external dependencies, IMHO, seriously increases the risk of future changes introducing problems with existing documentation using QuickBook. But again, this only applies if the intention is to expose such abilities available to QuickBook users so they can create custom, project-specific syntax highlight definitions.
Interesting! I never looked at it as deeply as you have. But you surely are right. I'm not sure how best to add "local definitions". Perhaps the best I can think of is to have it in the quickbook "qbk" file itself.
QuickBook provides a mechanism to expose certain entities (such as a logo) and refer to them by name. I was thinking if the syntax highlighting could be done in a similar way, using QuickBook syntax (thus reducing the number of syntaxes that need to be learned. Thus, we have something like:
[syntax "C++"
[symbols "keyword" [red bold] [asm auto static_cast ...]]
[regex "operator" [lightgrey] "[{}-*]"]
[regex "string" [blue] "..."]
]
[syntax "Python" ...]It may also be useful to inherit syntaxes:
[syntax "C" ...] [syntax "C++" inherit "C" ...] [syntax "SGML" ...] [syntax "XML" inherit "SGML" ...] [syntax "HTML" inherit "XML" ...]
QuickBook would then keep a run-time structure that defines the regexes and symbols that make a syntax. Then, you can use that when you identify a code block that is marked as being auto-highlighted.
Another useful markup would be to import a qbk file, a. la. #include and <xsl:import/>. This would make it easier to organise quickbook documents and syntaxes. Having a command line option to specify the search directories (asside from the directory the main qbk file is in) would then make it easy to switch between syntaxes/highlighting schemes.
[example -- document.qbk [import cpp-syntax.qbk]
-- cpp-syntax.qbk [import c-syntax.qbk] --end example]
With the above syntaxes, the symbol/regex definitions are bound to the colour/format schemes. It may be useful to separate these out, allowing:
[highlighting [keywords red bold] [comments "C++" teal] [comments "C" cyan] [preprocessor bold olive] ]
These are just ideas. I am not sure how feasible they may be.
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
