From: Eric Mahurin <eric_mahurin@...>
Date: 2005-06-25T05:34:48+09:00
Subject: Re: [ANN] Application-0.6.0

--- Jim Freeze <jim@freeze.org> wrote:

> > I have a few more comments:
> > 
> > * allow the definition of long_description to appear in
> > comments above the application class with all of the rdoc
> > formatting (you'll need to parse $0 with rdoc utilities). 
> I
> > think this gives a more ruby-like way of documenting
> scripts.
> 
> I take patches. ;)

sorry, busy with my own ruby coding right now...

> If this is supported, how do you suggest handling the
> existance of
> both long_description and rdoc.

If you figure out how to get this working, maybe
long_description would be obsolete.  For any reasonable size
script, embedding the long_description where it is now would
probably create too much clutter.  Putting it in comments using
rdoc formatting would seem to make more sense.

> > * make a certain set of options enabled by default: man
> page,
> > version, usage, etc.  That way all applications written in
> this
> > framework will immediately have this commonality.  And then
> > have a way for the application class to delete this
> > functionality if it isn't wanted for some strange reason.
> 
> Hmm, haven't thought about that, but sounds reasonable.
> If I follow the rails framework, then this would be a
> scaffold. However, I have not mentioned what is behind
> curtain
> #3, but I can tell you it is something that will generate
> a project directory structure and an application skeleton.
> This skeleton (scaffold in rails speak) could just include
> them as they are done now.
> 
> Would this be ok or do you still think there should be
> implicit options that a user must delete?

Since I have no knowledge of rails and don't know what's behind
curtain #3, I don't know what you are talking about.

> > * automatic usage generation (on your TODO already?).  You
> > should also allow a short description for the options and
> > arguments so that each option/arg will come out in a single
> > line.
> 
> This is already supported. Here are the rules:
> 
>     -x  Single character options desc. goes on same line.
> 
>     --x Double dash and single character options desc. goes
> on the same line.
> 
>     ---x
>         Triple dash and single character desc. goes on the
> next
>         line.
> 
>     --y Double dash and single character options description
> that wraps to
>         the next line.
> 
> You usually only see this for POSIX options.

What I meant was that you should have short description for the
usage and a long description for the man page.  For example,
compare gzip -h (usage) vs. man gzip (full docs).  One has a
few words per option and the other a full paragraph per option.

> > * in your examples, show how the options are accessed by
> main.
> > 
> > This looks very similar to a package I wrote for perl years
> ago
> > (option/arg parsing, automatic usage, semi-automatic man
> page
> > handling).  On man pages for that package, I decided to
> > automatically generate POD (like rdoc comments) from the
> > option/arg description and then have programmer paste it in
> the
> > script and maintain it.  I believe the way you are doing it
> is
> > a more maintainable approach (i.e. when you
> add/change/delete
> > an option the man page is automatically updated), but the
> man
> > page formatting is not very flexible.  Probably a good
> > tradeoff.
> 
> What about adding a #to_rdoc so the app can document itself?
> 
> -- 
> Jim Freeze
> 
> 



		
__________________________________ 
Yahoo! Mail 
Stay connected, organized, and protected. Take the tour: 
http://tour.mail.yahoo.com/mailtour.html