Reece Dunn wrote:
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.
Wonderful idea! It all boils down to:
1) Having a qbk include mechanism.
2) Providing a command line switch to specify the search directory
for includes
4) Having a default.qbk automatically included.
<<This is important for backward compatibility. The
default.qbk contains the current highlighting schemes>>
I think this is all very reaonable.
I'm not sure however if its a good idea to go as far as
specifying the colors for each. That's the job of the CSS
file. Do you want the ability to rewrite the CSS file too?
Nah, that's too much, I think.
Cheers,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net
-------------------------------------------------------
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
