DRY and embedded docs.
Hugh Sasse Staff Elec Eng
print <<"END"
usage #{$0} options arguments
where option is
-a (or whatever)
....
-z ( i.e a whole load of these)
END
How can I get this text into a
=begin
=end
section so I can have it as documentation, without breaking the
Don't Repeat Yourself rule?
I cannot do
print <<"END"
=begin
usage #{$0}.....
=end
END
because the =begin and =end are no longer considered documentation
by ruby. They may be by some other program, admittedly, but they
end up in the string created by the here document, which I don't
want. Clearly one may need to put lines beginning with = in a here
document, so ruby _is_ doing the right thing, but I cannot have the
lines considered to be both a here document and embedded documentation.
Is there a cunning way round this without generating my ruby from
m4 or some such?
Hugh
h...@dmu.ac.uk
Dave Thomas
> If I have a here document in some ruby program:
>...
> How can I get this text into a
> =begin
> =end
> section so I can have it as documentation, without breaking the
> Don't Repeat Yourself rule?
> .....
And a darn fine rule it is too.. ;-)
This is kind of tacky, but it does work--both rd and the program can
access the same explanatory text:
def usage
copying = false
while DATA.gets
break if /^=end/
if /^=begin/
copying = true
else
print if copying
end
end
end
usage() unless ARGV.length >= 2
puts "Body of program..."
__END__
=begin
Here is my documentation.
prog [ option ... ] file1 file2
Options:
-a all
-b before
-c change
=end
Now, I just had a thought... Wouldn't it be neat if rdtool had an
option that did just this, so you could say
RD::usage
and it would format up the text neatly for you?
Dave
Hugh Sasse Staff Elec Eng
> And a darn fine rule it is too.. ;-)
:-)
>
> This is kind of tacky, but it does work--both rd and the program can
> access the same explanatory text:
>
[Example of reading DATA trimmed]
That is an interesting idea. I think that will solve my
problem, and it can be extended for more sophisticated parsing
(picking up different bits to insert). Thinking outside the
box almost literally. :-)
>
> Dave
>
>
Hugh
h...@dmu.ac.uk
Dave Thomas
> Hi,
>
> In message "[ruby-talk:04344] Re: DRY and embedded docs."
> on 00/08/08, Dave Thomas <Da...@thomases.com> writes:
> >Now, I just had a thought... Wouldn't it be neat if rdtool had an
> >option that did just this, so you could say
> >
> > RD::usage
> >
> >and it would format up the text neatly for you?
>
> What does it mean?
> RDtool should do same thing your usage does?(i.e. simply output RD
> in script file to STDOUT?)
> Or, in addition, format it into some kind of format(ex. plain text
> but formatted) and output to STDOUT?
I think the latter would be nice. Perhaps it should look for an entry
such as
= Usage
and just format that. That way, you could just output the usage
section of a larger RD document.
What do people think?
Dave
Dave Thomas
> RD seems plain text. so, when you want instant plain text output
> which dosn't need to parse RD exactly (ex: printing Usage message),
> there is a way to format RD into plain text with much lower cost
> than RDtool's, maybe.
That's a good point. I was also think we could probably benefit from
integrating this with getoptlong as well.
Dave
Hal E. Fulton
conclusions... :)
When a usage message is printed, efficiency matters
very little. Milliseconds are insignificant when the user
is expected to spend several seconds visually scanning
the output...
Of course, it might be considered a little inelegant. There
might still be A Better Way...
Hal
----- Original Message -----
From: Toshiro Kuwabara <tosh...@yb3.so-net.ne.jp>
To: ruby-talk ML <ruby...@netlab.co.jp>
Sent: Tuesday, August 08, 2000 10:03 AM
Subject: [ruby-talk:04354] Re: DRY and embedded docs.
> Hi,
>
> In message "[ruby-talk:04353] Re: DRY and embedded docs."
> on 00/08/08, Dave Thomas <Da...@thomases.com> writes:
> >I think the latter would be nice. Perhaps it should look for an entry
> >such as
> >
> > = Usage
> >
> >and just format that. That way, you could just output the usage
> >section of a larger RD document.
> >
> >
> >What do people think?
>
> Printing Usage message is one of user interface, so a program
> should print it as quickly as possible, but RDtool way of
> parsing RD is highly costed, maybe.
>
> RD seems plain text. so, when you want instant plain text output
> which dosn't need to parse RD exactly (ex: printing Usage message),
> there is a way to format RD into plain text with much lower cost
> than RDtool's, maybe.
>
> ---
> Tosh
> Toshiro Kuwabara
>
>
Toshiro Kuwabara
In message "[ruby-talk:04344] Re: DRY and embedded docs."
on 00/08/08, Dave Thomas <Da...@thomases.com> writes:
>Now, I just had a thought... Wouldn't it be neat if rdtool had an
>option that did just this, so you could say
>
> RD::usage
>
>and it would format up the text neatly for you?
What does it mean?
RDtool should do same thing your usage does?(i.e. simply output RD
in script file to STDOUT?)
Or, in addition, format it into some kind of format(ex. plain text
but formatted) and output to STDOUT?
---
Tosh
Toshiro Kuwabara
Toshiro Kuwabara
In message "[ruby-talk:04353] Re: DRY and embedded docs."
on 00/08/08, Dave Thomas <Da...@thomases.com> writes:
Conrad Schneiker
"Hal E. Fulton" wrote:
>
> Your premises are correct, but I disagree with your
> conclusions... :)
>
> When a usage message is printed, efficiency matters
> very little. Milliseconds are insignificant when the user
> is expected to spend several seconds visually scanning
> the output...
>
> Of course, it might be considered a little inelegant. There
> might still be A Better Way...
>
> Hal
>
> ----- Original Message -----
> From: Toshiro Kuwabara <tosh...@yb3.so-net.ne.jp>
> To: ruby-talk ML <ruby...@netlab.co.jp>
> Sent: Tuesday, August 08, 2000 10:03 AM
> Subject: [ruby-talk:04354] Re: DRY and embedded docs.
>
> > Hi,
> >
> > In message "[ruby-talk:04353] Re: DRY and embedded docs."
> > on 00/08/08, Dave Thomas <Da...@thomases.com> writes:
> > >I think the latter would be nice. Perhaps it should look for an entry
> > >such as
> > >
> > > = Usage
> > >
> > >and just format that. That way, you could just output the usage
> > >section of a larger RD document.
> > >
> > >
> > >What do people think?
> >
> > Printing Usage message is one of user interface, so a program
> > should print it as quickly as possible, but RDtool way of
> > parsing RD is highly costed, maybe.
I'm not familiar with all the formatting features, but is included files
one of them? Also, what if you have multiple "= Usage" entries (perhaps
with the relevant code)? Would they be concatenated? In a large
multi-file program, such types of processing might take a noticeable
amount of time. JM2CW
--
Conrad Schneiker
(This note is unofficial and subject to improvement without notice.)
Hal E. Fulton
> Of course, milli-seconds are few enough.
> But RDtool's parsing cost is much larger, order is 1/10 seconds.
> Although 1/10 seconds is not so long time, it is long enough to
> irritate users if they need to look usage message frequently,
> I think.
>
In that case, I think you are correct. A delay that is visible to the user
at all is unacceptable, and 100 msec is probably within that boundary.
Hal
Toshiro Kuwabara
In message "[ruby-talk:04355] Re: DRY and embedded docs."
on 00/08/08, Dave Thomas <Da...@thomases.com> writes:
>That's a good point. I was also think we could probably benefit from
>integrating this with getoptlong as well.
FYI: if you want option analizing lib to print pretty formated Usage
message semi-automatically, Nakada's OptionParser is one of options.
<URL:http://www.ruby-lang.org/en/raa-list.rhtml?name=OptionParser>
It's my favorite. :-)
---
Tosh
Toshiro Kuwabara
Toshiro Kuwabara
In message "[ruby-talk:04360] Re: DRY and embedded docs."
on 00/08/08, "Hal E. Fulton" <hfu...@austin.rr.com> writes:
>Your premises are correct, but I disagree with your
>conclusions... :)
>
>When a usage message is printed, efficiency matters
>very little. Milliseconds are insignificant when the user
>is expected to spend several seconds visually scanning
>the output...
Of course, milli-seconds are few enough.
But RDtool's parsing cost is much larger, order is 1/10 seconds.
Although 1/10 seconds is not so long time, it is long enough to
irritate users if they need to look usage message frequently,
I think.
---
Tosh
Toshiro Kuwabara