From rosco at roscopeco.co.uk Mon Nov 28 13:27:51 2005 From: rosco at roscopeco.co.uk (Ross Bamford) Date: Mon, 28 Nov 2005 18:27:51 -0000 Subject: [Rote-devel] [ANN] Rote - Textual templating for website and docs In-Reply-To: <438B338A.4000305@gmail.com> References: <438AE729.4010104@gmail.com> <438B338A.4000305@gmail.com> Message-ID: (Lionel, hope you don't mind me CCing to the Rote mailing list?) On Mon, 28 Nov 2005 16:42:50 -0000, Lionel Thiry wrote: > Ross Bamford a ?crit : >> On Mon, 28 Nov 2005 11:16:57 -0000, Lionel Thiry >> wrote: >> >>> Ross Bamford a ?crit : >>> >>>> [snip] >>>> So now theres no excuse for skipping out on the documentation ;) - >>>> come on >>>> over and check it out at http://rote.rubyforge.org/ . >>>> >>>> [snip] >>>> >>> >>> From your site: >>> "Rote is somewhat similar to (though simpler than) WebGen , which >>> provides a richer environment geared more toward websites and content >>> publishing (whereas Rote?s implementation as an extension to Rake >>> reflects a bias toward software documentation).". >>> >>> It really looks like you have implemented what I had suggested to >>> webgen >>> in the past but couldn't be implemented as it didn't fit in its design. >>> I'd really like to know, have I inspired you to do this? >>> >> >> Hi Lionel, >> >> I certainly did take a lot of inspiration from comments and ideas I >> saw, as well as from my other life in Java (Keeping site with doc is >> something I've done on all my public projects since I started using >> Maven), so yes, I guess your ideas influenced Rote a fair bit :). To be >> honest, I've not been Rubying for all that long (I used it for basic >> shell scripting-type stuff since a while back, but only got into really >> figuring it out about a month ago), and I was quite surprised that >> there didn't seem to be much in the way of templating aimed >> specifically at software doco. I'm as bad as anyone - if it takes more >> than a little setup, I tend to 'forget' all about documentation until >> late in the game... >> >> I did a search, but I'm not sure I found everything you said relating >> to Webgen. I'd love to know what you think about Rote and how it could >> be improved. >> >> Cheers, >> Ross >> >> (P.s. I just released Rote 0.1.6, with a slightly expanded >> documentation set, which also acts as an example ;) ). >> > > Thank you for answering :) > No problem. Nice to meet you. :) > > All the topics I once opened are now closed, but you can easily see them > here: > http://rubyforge.org/tracker/index.php?group_id=296&atid=1210 > > Here, I asked for erb in webgen: > http://rubyforge.org/tracker/index.php?func=detail&aid=1847&group_id=296&atid=1210 > > Here, I talked about the possible use of rake in webgen: > http://rubyforge.org/tracker/index.php?func=detail&aid=1830&group_id=296&atid=1210 > > And here, I talked about the contrast between programmatic and > descriptivist approach: > http://rubyforge.org/tracker/index.php?func=detail&aid=2083&group_id=296&atid=1210 > > > What surprised me about Rote is that it addresses those problems. If you > haven't read my posts, it would be even more surprising! ;) > It appears we think along the same lines :) As I say, I did a lot of surfing when I was thinking about Rote, so it's probably the case that I did pick up on your ideas then. My subconcious tends to file things away like that for me ;) From your suggestions to Webgen I'm pretty sure you're going to like Rote - esp your feelings on the programmatic approach and as little config as possible. > > I do not fully understand how rote works yet... although I already have > some questions: > > *) You say "Simple set-up based on page templates and sections.". What > are sections? > Directories ;) At the moment they don't do much, but I have a few features in mind, like allowing a directory of pages to be treated as a single entity, and making it easy to have per-section navigation put together. Another idea I have (I want it for the docs) is to have the ability to have a directory of pages, and get not only the pages rendered, but also have all pages in the section rendered to a single file too. This would make it really easy to do those 'Page per section' or 'single large page' optional docs, for example. > *) You say "?Scoped? Ruby code support allows fine-grained control of > data available across all documentation, a subset, or individual > pages.". What does it mean and what does it allow? > I'm not really happy with the term 'scope', but not sure what else fits... It's basically referring to the fact that code can be run for a given page from one of several places: * Across the whole site, from a top-level COMMON.rb * Across a single section, from it's own COMMON.rb. You don't have to inherit from the directory above's COMMON.rb, but the way this works is a bit messy and needs to be fixed. * On a single page, by having a .rb file with the same base-name as the page, or including code in ERB <% %>. * On a single run of a single page, by providing a custom Page instance with a block. This option isn't very well exposed yet, though. At the moment there are some problems (like the first option not working properly, thanks to the second - I'm thinking of adding an optional GLOBAL.rb for the top-level), but generally what happens is they're evaluated (if found) in order using instance_eval on the Page, so that by the time the template and layout are rendered the Page will have whatever setup you gave it, plus any instance vars / methods you defined. > *) Never thought of using Rant in addition or instead of Rake? ( > http://make.rubyforge.org/ ) > I honestly haven't looked at Rant yet, and I never say never... I don't want to lose Rake integration but I'll definitely take a look at Rant - the more widely applicable this is, the better! > > In practice, I'm good at having ideas, but I'm pretty bad once I want to > implement them. I'm really glad you've done it for me! ;) > :) I'm glad you found it interesting (and maybe useful). On the ideas front, I have a few things I want to add, but really I'm just using my own website (and the docs) to drive development, so that's pretty narrow. If you have any ideas to improve Rote I'd be very grateful to hear them, either here or on the tracker: http://rubyforge.org/tracker/?atid=4406&group_id=1120&func=browse Cheers, Ross -- Ross Bamford - rosco at roscopeco.co.uk