[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

[rdoc] sections-patch

Michael Neumann

12/3/2004 2:08:00 AM

Hi,

With the patch below, it's possible to wrap :section: tags like this:

# - - - - - - - - - - - - - - - - - -
# :section: Section-header
# - - - - - - - - - - - - - - - - - -

Regards,

Michael


RCS file: /var/cvs/src/ruby/lib/rdoc/markup/simple_markup.rb,v
retrieving revision 1.2
diff -r1.2 simple_markup.rb
306a307,312
> if /^(-\s){3,}/ =~ active_line
> line.stamp(Line::BLANK, 0)
> return
> end
>
>
Index: lib/rdoc/parsers/parse_rb.rb
===================================================================
RCS file: /var/cvs/src/ruby/lib/rdoc/parsers/parse_rb.rb,v
retrieving revision 1.35
diff -r1.35 parse_rb.rb
2313c2313
< context.set_current_section(param, comment)
---
> context.set_current_section(param, (comment =~
/:section:(.*)\n/m) ? $1 : comment)
7 Answers

Dave Thomas

12/4/2004 5:38:00 AM

0


On Dec 2, 2004, at 20:07, Michael Neumann wrote:

> Hi,
>
> With the patch below, it's possible to wrap :section: tags like this:
>
> # - - - - - - - - - - - - - - - - - -
> # :section: Section-header
> # - - - - - - - - - - - - - - - - - -

Michael:

I've done something that has the same effect, but which I think is more
general.

You can now have any number of lines before :section: in the comment
block. These will be stripped from the output. In addition, if the same
lines appear at the end of the block, they'll be ignored to.

This means that

# :section: My Section
# This is the section
# that I wrote

# ---------------------------------
# :section: My Section
# This is the section
# that I wrote
# ---------------------------------

and

# SECTION SECTION SECTION
# !!!! !!!! !!!! !!!!
# :section: My Section
# This is the section
# that I wrote
# SECTION SECTION SECTION
# !!!! !!!! !!!! !!!!

will all generate the same output.

I've checked the change into the 1.8 and 1.9 HEADs


Cheers

Dave

Michael Neumann

12/4/2004 1:01:00 PM

0

Dave Thomas wrote:
>
> On Dec 2, 2004, at 20:07, Michael Neumann wrote:
>
>> Hi,
>>
>> With the patch below, it's possible to wrap :section: tags like this:
>>
>> # - - - - - - - - - - - - - - - - - -
>> # :section: Section-header
>> # - - - - - - - - - - - - - - - - - -
>
>
> Michael:
>
> I've done something that has the same effect, but which I think is more
> general.

Great!

> You can now have any number of lines before :section: in the comment
> block. These will be stripped from the output. In addition, if the same
> lines appear at the end of the block, they'll be ignored to.

How about this idea:

Lines before a section are handled as usual (how would they be handled?
Probably best would be to ignore them). Lines after the section are
included in the section description. Lines with two ## in front are ignored.

This would allow:

# :section: My Section
# Description of My Section...
# ...

or:

## This is an rdoc comment
##---------------------------------------------
# :section: My Section
# Description of My Section
##---------------------------------------------

The description (if given) would be included in the Contents and after
each Section-header.

What do you think?

Regards,

Michael

Dave Thomas

12/4/2004 2:12:00 PM

0


On Dec 4, 2004, at 7:01, Michael Neumann wrote:

> Lines before a section are handled as usual (how would they be
> handled? Probably best would be to ignore them). Lines after the
> section are included in the section description. Lines with two ## in
> front are ignored.
>

> What do you think?

I'm not sure I see the benefit, but I'm probably being dense today. I
was aiming for a solution that would meet your original requirement,
but that would also be fairly natural to use and unobtrusive in the
user's source code.

Cheers

Dave

Michael Neumann

12/4/2004 2:23:00 PM

0

Dave Thomas wrote:
>
> On Dec 4, 2004, at 7:01, Michael Neumann wrote:
>
>> Lines before a section are handled as usual (how would they be
>> handled? Probably best would be to ignore them). Lines after the
>> section are included in the section description. Lines with two ## in
>> front are ignored.
>>
>
>> What do you think?
>
>
> I'm not sure I see the benefit, but I'm probably being dense today. I
> was aiming for a solution that would meet your original requirement, but
> that would also be fairly natural to use and unobtrusive in the user's
> source code.

I am totally happy with your current implementation. I only thought,
that sometimes it would be nice to describe the sections.

Now I've another idea ;-)

Collect all sections (of all files) and display them similar as the
"Files", "Classes" and "Methods" pane. For each section display all
methods that are in this section (of all classes).

But that's only a brief idea, nothing concrete...

Thanks so far.

Regards,

Michael

Dave Thomas

12/4/2004 3:11:00 PM

0


On Dec 4, 2004, at 8:23, Michael Neumann wrote:
> I am totally happy with your current implementation. I only thought,
> that sometimes it would be nice to describe the sections.

You can do that (and the description appears under the section in the
output). The recent patch allows you to add your separator lines before
and after the description.

> Collect all sections (of all files) and display them similar as the
> "Files", "Classes" and "Methods" pane. For each section display all
> methods that are in this section (of all classes).

Absolutely - that's in the plans. But first, I have to see if people
actually use the section idea. If it takes off, then I'll add lots of
different bells and whistles for it. If not, then I won't clutter the
code with extra stuff :)


Cheers

Dave

Michael Neumann

12/4/2004 3:28:00 PM

0

Dave Thomas wrote:
>
> On Dec 4, 2004, at 8:23, Michael Neumann wrote:
>
>> I am totally happy with your current implementation. I only thought,
>> that sometimes it would be nice to describe the sections.
>
>
> You can do that (and the description appears under the section in the
> output). The recent patch allows you to add your separator lines before
> and after the description.
>
>> Collect all sections (of all files) and display them similar as the
>> "Files", "Classes" and "Methods" pane. For each section display all
>> methods that are in this section (of all classes).
>
>
> Absolutely - that's in the plans. But first, I have to see if people
> actually use the section idea. If it takes off, then I'll add lots of
> different bells and whistles for it. If not, then I won't clutter the
> code with extra stuff :)

Sure. What is even more useful IMO, is the ability to group
classes/modules into sections, not just methods. Looking at some rdoc
documentations, you see lots of classes, but don't see their
relationship. If all this information is available, one could write a
dynamic CGI-application, that behaves similar as a smalltalk class
browser... similar to ri but much more powerful.

Regards,

Michael

Werner Maier

12/5/2004 6:27:00 PM

0

Michael Neumann schrieb:
> Dave Thomas wrote:
>
>>
>> On Dec 4, 2004, at 8:23, Michael Neumann wrote:
>>
>>> I am totally happy with your current implementation. I only thought,
>>> that sometimes it would be nice to describe the sections.
>>
>>
>>
>> You can do that (and the description appears under the section in the
>> output). The recent patch allows you to add your separator lines
>> before and after the description.
>>
>>> Collect all sections (of all files) and display them similar as the
>>> "Files", "Classes" and "Methods" pane. For each section display all
>>> methods that are in this section (of all classes).
>>
>>
>>
>> Absolutely - that's in the plans. But first, I have to see if people
>> actually use the section idea. If it takes off, then I'll add lots of
>> different bells and whistles for it. If not, then I won't clutter the
>> code with extra stuff :)
>
>
> Sure. What is even more useful IMO, is the ability to group
> classes/modules into sections, not just methods. Looking at some rdoc
> documentations, you see lots of classes, but don't see their
> relationship. If all this information is available, one could write a
> dynamic CGI-application, that behaves similar as a smalltalk class
> browser... similar to ri but much more powerful.
>
> Regards,
>
> Michael
>
>
yes, sure :)


Werner