In my day job I’m a sas (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.
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.
I did some customizing of rdoc for my web site, 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: [email protected]
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) 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.
I did some customizing of rdoc for my web site, 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.
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.
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
This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.