# OT(?): Adapting rdoc to produce documentation for something other than ruby or c--advisable? **URL:** \ **Category:** Ruby\ **Created:** [April 14, 2010, 6:00pm UTC](https://www.ruby-forum.com/t/ot-adapting-rdoc-to-produce-documentation-for-something-other-than-ruby-or-c-advisable/186947 "2010-04-14T18:00:53Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![casper\_the\_ghost](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/58956e/32.png) [@casper\_the\_ghost](https://www.ruby-forum.com/u/casper_the_ghost)\ **Post date:** [April 14, 2010, 6:00pm UTC](https://www.ruby-forum.com/t/ot-adapting-rdoc-to-produce-documentation-for-something-other-than-ruby-or-c-advisable/186947/1 "2010-04-14T18:00:53Z")
Hey All, In my day job I’m a sas ([www.sas.com](http://www.sas.com)) programmer. I’ve got a plain text file of sas macros (roughly equivalent to ruby’s methods) for which I would love to have rdoc-style documentation. Specifically, I’d like a list of the macros, the params they take, the explanatory comments that precede each one & the expandable code listing when you click a method name. A brief troll through the RDoc::Markup docs makes me wonder if I couldn’t learn to drive that sufficiently to get rdoc to do this for me. Can anybody give me a sense for how badly RDoc & I would have to torture one another to get this to work? In case it’s helpful, sas has c-style comments: ‘\*’ starts a comment until the first following ‘;’ char. Macro definitions are preceded by the keyword %macro, followed by a name & an optional parenthesized, comma-delimited list of paraameters. All lines up to the first following %mend keyword are the body of the macro. Many thanks! -Roy ---
**Author:** ![casper\_the\_ghost](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/58956e/32.png) [@casper\_the\_ghost](https://www.ruby-forum.com/u/casper_the_ghost)\ **Post date:** [April 14, 2010, 6:33pm UTC](https://www.ruby-forum.com/t/ot-adapting-rdoc-to-produce-documentation-for-something-other-than-ruby-or-c-advisable/186947/2 "2010-04-14T18:33:41Z")
Hei, I know SAS and honestly I don’t think that RDoc is suitable for the task: the syntax has more than one case that you will have to handle yourself. If you want to get it working you’ll have to hack the parser yourself and I don’t think that will be very easy. HTH! – Andrea D. > **[GitHub - bolthar/freightrain: Ruby desktop development made easy](https://github.com/bolthar/freightrain)** > > Ruby desktop development made easy. Contribute to bolthar/freightrain development by creating an account on GitHub. > **[using (IMHO)](https://usingimho.wordpress.com/)** > > Andrea Dallera 's blog ---
**Author:** ![casper\_the\_ghost](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/58956e/32.png) [@casper\_the\_ghost](https://www.ruby-forum.com/u/casper_the_ghost)\ **Post date:** [April 14, 2010, 8:14pm UTC](https://www.ruby-forum.com/t/ot-adapting-rdoc-to-produce-documentation-for-something-other-than-ruby-or-c-advisable/186947/3 "2010-04-14T20:14:58Z")
Hi Roy, I did some customizing of rdoc for my web site, [rubydox.net](http://rubydox.net). In my case I wanted to override the default rdoc → html formatting as well has the final object model → file output. I have played with the source file parsing, but rdoc already has a number of file parsers for different file types (ruby, plain text, etc). You’ll probably have to use a mixin like I did to hook your code in but it should be possible. Dah dan drew \> brilliantsoftware.ca \> shouldn’t your software be brilliant? From: removed\_email\_address@domain.invalid Sent: Wednesday, April 14, 2010 12:00 PM Newsgroups: comp.lang.ruby To: ruby-talk ML Subject: OT(?): Adapting rdoc to produce documentation for something other than ruby or c–advisable? Hey All, In my day job I’m a sas ([www.sas.com](http://www.sas.com)) programmer. I’ve got a plain text file of sas macros (roughly equivalent to ruby’s methods) for which I would love to have rdoc-style documentation. Specifically, I’d like a list of the macros, the params they take, the explanatory comments that precede each one & the expandable code listing when you click a method name. A brief troll through the RDoc::Markup docs makes me wonder if I couldn’t learn to drive that sufficiently to get rdoc to do this for me. Can anybody give me a sense for how badly RDoc & I would have to torture one another to get this to work? In case it’s helpful, sas has c-style comments: ‘\*’ starts a comment until the first following ‘;’ char. Macro definitions are preceded by the keyword %macro, followed by a name & an optional parenthesized, comma-delimited list of paraameters. All lines up to the first following %mend keyword are the body of the macro. Many thanks! -Roy ---
**Author:** ![casper\_the\_ghost](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/58956e/32.png) [@casper\_the\_ghost](https://www.ruby-forum.com/u/casper_the_ghost)\ **Post date:** [April 14, 2010, 11:10pm UTC](https://www.ruby-forum.com/t/ot-adapting-rdoc-to-produce-documentation-for-something-other-than-ruby-or-c-advisable/186947/4 "2010-04-14T23:10:37Z")
On Apr 14, 11:13 am, Dan D. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > Hi Roy, > > I did some customizing of rdoc for my web site, [rubydox.net](http://rubydox.net). In my case I wanted to override the default rdoc → html formatting as well has the final object model → file output. I have played with the source file parsing, but rdoc already has a number of file parsers for different file types (ruby, plain text, etc). You’ll probably have to use a mixin like I did to hook your code in but it should be possible. > > Dan Thanks Dan & Andrea! I maybe should say that I don’t expect the SAS code in the body of the macro to by syntax-highlighted. That would be lovely of course, but not at all necessary. Just recognized as programming code to be tucked into the togglable div (or however the show/hide code stuff is implemented) would be a win for me. Thanks! -Roy ---
**Author:** ![casper\_the\_ghost](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/58956e/32.png) [@casper\_the\_ghost](https://www.ruby-forum.com/u/casper_the_ghost)\ **Post date:** [April 14, 2010, 11:36pm UTC](https://www.ruby-forum.com/t/ot-adapting-rdoc-to-produce-documentation-for-something-other-than-ruby-or-c-advisable/186947/5 "2010-04-14T23:36:57Z")
On Apr 14, 2010, at 09:00, removed\_email\_address@domain.invalid wrote: > Can anybody give me a sense for how badly RDoc & I would have to > torture one another to get this to work? > > In case it’s helpful, sas has c-style comments: ‘\*’ starts a comment > until the first following ‘;’ char. Macro definitions are preceded by > the keyword %macro, followed by a name & an optional parenthesized, > comma-delimited list of paraameters. All lines up to the first > following %mend keyword are the body of the macro. If you’ve got input files that aren’t already handled (ruby, C, text, perl are handled built-in, fortan is available via an extension) you’ll want to look at writing a parser. RDoc::Parser::C is a pile of regular expressions (which would probably work best to start), or if you can find (or write) a real parser for SAS macros you can use that instead. An RDoc::Parser will turn an input document (like your SAS file) into a tree of code built around an RDoc::TopLevel (a file) and it’s various descendents (lib/rdoc/code\_objects.rb has the list). You’ll need to decide on a mapping from the elements of SAS macros to classes, modules, and methods. ---
**Author:** ![casper\_the\_ghost](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/58956e/32.png) [@casper\_the\_ghost](https://www.ruby-forum.com/u/casper_the_ghost)\ **Post date:** [April 15, 2010, 3:00pm UTC](https://www.ruby-forum.com/t/ot-adapting-rdoc-to-produce-documentation-for-something-other-than-ruby-or-c-advisable/186947/6 "2010-04-15T15:00:43Z")
On Apr 14, 2:32 pm, Eric H. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > If you’ve got input files that aren’t already handled (ruby, C, text, perl are handled built-in, fortan is available via an extension) you’ll want to look at writing a parser. > > RDoc::Parser::C is a pile of regular expressions (which would probably work best to start), or if you can find (or write) a real parser for SAS macros you can use that instead. > > An RDoc::Parser will turn an input document (like your SAS file) into a tree of code built around an RDoc::TopLevel (a file) and it’s various descendents (lib/rdoc/code\_objects.rb has the list). You’ll need to decide on a mapping from the elements of SAS macros to classes, modules, and methods. Cool–thanks Eric. I browsed just a bit through RDoc::Parser::C & may give this a shot. Probably first I should try a ‘hello world’ type thing where I just try to get rdoc to emit docs for a pretend module/ method w/out any regard to the actual contents of any real file & then see how far I can get w/simple regexes. Thanks! -Roy