Re: [Cheetahtemplate-discuss] User-contributed recipes/documentation

[R. T. B. <ty...@sl...>]

On Mon, Jun 01, 2009 at 09:09:06PM -0700, Tavis Rudd wrote:
> On Sun, 31 May 2009, R. Tyler Ballance wrote:
>
>> On Thu, May 28, 2009 at 04:02:05PM -0700, R. Tyler Ballance wrote:
>>> Over the weekend I started working on writing some Cheetah documentation
>>> in Cheetah and I suppose I should at least share my work (thus far).
>>
>> I started playing with Sphinx today (http://sphinx.pocoo.org/) and I
>> think I might just move everything over into Sphinx land.
>>
>> I'm hoping to recreate the user's guide and get more comprehensive, and
>> alive, documentation going with Sphinx (which primarily uses
>> reStructured text, similar to Markdown).
>>
>> The little bit of code I toyed around with for the "current" recipes
>> stuff linked in the parent post was fun, but unfortunately the macro
>> support in Cheetah I don't think is good enough for me to use Cheetah to
>> document itself.
>
> It sounds like you were trying to use the macro stuff for something it's  
> not intended for: embedding raw chunks of cheetah source that should not 
> be parsed or compiled.  I'd suggest you look at the #raw directive or the 
> compiler settings 'cheetahVarStartToken', 'directiveStartToken', etc.

Not quite, I was using macros as a way of further extending Cheetah
syntax via Cheetah itself :) Very "turtles all the way down" sort of
stuff ;)

I was basically trying to combine Markdown with some custom defined
macros like `#highlight/#end highlight` (for source highlighting) to
extend Cheetah to be more documenting friendly (the task I was working
on). 

> As an aside, if no one is using the #macro stuff I wouldn't object to  
> ripping it out.  I now have a much cleaner, simpler way of accomplishing  
> what I wanted from it.

The macro stuff isn't bloody documented except for terse code snippets
and the bits in the CHANGES.txt of old, which is where I gleaned my
knowledge of it from ;).

I don't think it should be ripped out, I'm kind of fond of expressing
new directives experimentally as macros, and then seeing whether they
should be incorporated more directly into the core of Cheetah
(unfortunately currently macro support makes this implausible)


Cheers
-- 
-R. Tyler Ballance
Slide, Inc.