Re: [Boost-docs] Re: Dynamically Loadable Syntax Highighters [ Was Re: [ANN] QuickBook 1.0 now in boost/tools]

[James Fowler]

Joel de Guzman wrote: Wow. I wish I was as eloquent as you are. ... Thanks, but be careful what you wish for!  I imagine there a rare, gifted few, whose "eloquence" drips from their fingers whenever they wish.  For me, while some it may be raw talent, most of it is just work. I suspect that most who recognize eloquence can write more eloquently than they realize, if they take the time to do so.  Think of it as a refactoring exercise.  Express what you want to communicate, and then start revising, pruning, editing, until your message is clear and compelling.  Keep stepping back, imagining someone else wrote it, and asking yourself "is it eloquent?" until it is.  Just make sure what you have to say is really worth saying eloquently, because otherwise (unless you're one of those few) you'll never have time for anything more than writing email...  You'll probably notice over time that I don't (can't!) always write like that :) True. Needless to say, we are in agreement. Well, I have to admit that QuickBook started out as a weekend hack. I needed to write a demo application for Spirit and at the same time, I got increasingly tired churning out docs in html. I thought, well, maybe I can make my life easier. Elegance, robustness, etc., wasn't part of the plan. It just worked. Then, after a while, Eric (Niebler) picked it up and ported it to do BoostBook instead of HTML. Quite a few found it useful and added features, improved on it, etc. At this point, I'm pretty sure there's lots of room for improvement in both robustness and feature set. I liken QuickBook, as it is now, to the VW beetle. Sometimes the door won't open, but it gets you to where you want to go :-) It's not elegant. New reatures? Sure! But we need to fix the door first. Ah, but think deeper (I love helping people do that;).  Admit QuickBook a "weekend hack"?  Fine, as long as you do so in context!  Even a quick&dirty "hack" embodies the experience and intuition of its creator, especially when scratching that infernal "there must be a better way" itch.  Take away a dozen years of your development experience, and perhaps your "weekend hack" would be something else entirely - like a shiny little pebble instead of a seed already containing, hidden, the promise of what it can become.  Talent, channeled through experience and refined over years of optimistic dissatisfaction, becomes a driving force of creative _expression_.  By then, elegance and robustness don't always need to be part of the plan.  Joel, do you still ever write ugly code, or start with a design which you soon discard?  You may on occasion, but I'll bet you never do so when you are in the "zone", when you hear the muses speaking... in that moment, what you create is imprinted with everything are.  Some get there and begin to divert this power into their ego, forgetting (or perhaps never having realized) that an intrinsic part of the journey is that ever-present unease that things could be, should be better than they are - which means you ain't there yet, and abandoning humility destroys much of your traction on a rarely traveled road.  Those who retain their sense of wonder may find it difficult to recognize in their own efforts the merit they so clearly see in others'.   But hey, maybe that's what community is for :) As for the VW beetle, well...  I'll save that for another time, but if you infer from this that a) I like the comparison of QuickBook and the beetle, and b) I believe the VW beetle was, though perhaps in an atypical manner, incredibly elegant, you're on the right track.  Even when the door was stuck. ... If you are passionate about your feature suggestion, I'd say go for it! Perhaps you can collaborate with Thomas and work on what he has done so far. I'm passionate about getting people passionate... and besides, there's no way I accomplish everything I hope for on my own.  Still, I'll probably be giving QuickBook some special attention here and there. 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. hmm... that would simplify things for the case where a syntax highlight definition is used in only one file.  In fact, that might be an ideal solution, once we fill in another little gap - adding something like an [include ...] directive.  I already figured [include ...] was inevitable, as keeping a Boost library's entire (non-doxygen) documentation source in one file could get unwieldy.  If we also added directives to parse a parser like Thomas created, it seems to all snap in place.  Simple stuff can just be right there inline.  More complex "local" highlight definitions can be separated into an explicitly included qbk file, within that project's doc directory, which might make things more manageable.  Add in some startup options (with appropriate defaults) to register common shared "qbk" files to be implicitly included at key points, and we can easily add "built-in" highlighting support for new source code formats (and more things we haven't thought of yet).   Anyone see anything I'm missing?  Anyone else see this as obviously the right solution (this is _not_ a rhetorical question)?  And to think I started off trying to explain why simply having it in the "qbk" file itself might be too limiting... Joel, in this case the best you can think of may simply be the best anyone can think of! Ok, agreed 100%. As hinted in my replies above, you already know that my main concern is, ahem, time. I am already involved with a couple of projects, all of which involves a lot of my time. As much as I want to have cool features like you've suggested, alas, I do not have the time, and there are other priorities at the top of my list. That is the reason why I hinted on evolving quikcbook one small step at a time. That said, if you, or anyone, is intested on working on it, that will be awesome and will be very welcome. Well, time is certainly a big issue.  Is there an implied "which someone is willing to pay for" in that?  FWIW, one of my personal goals is to increase the exposure to, and adoption of, Boost and other open resources within the realm of corporate development groups using C++.  I've spent ten years doing this for commercial products.  Now I intend to focus some of my "eloquence" on building support for further Boost development.  If any of you work for or have contacts in a company you feel should be using and supporting Boost, but don't know how to bring it up, I'd be happy to help!  Such support should make more tangible, er, compensation available for tasks like enhancing the Boost Tools, especially when those with a proven history are involved.  But until then, rest assured that I feel your pain ;) - james -- __________________________________________________________ James Fowler, Open Sea Consulting http://www.OpenSeaConsulting.com, Marietta, Georgia, USA Do C++ Right. http://www.OpenCpp.org, opening soon!