Velocity Reviews > Ruby > bug in rdoc?

# bug in rdoc?

Wybo Dekker
Guest
Posts: n/a

 10-16-2006
-- The following example, is taken from the rdoc documentation.
For the long options, it converts -- into — (a long hyphen)
instead of two separate hyphens with some whitespace in between.
(see www.servalys.nl/ doc/index.html for the output)

=begin rdoc

<tt>--output</tt> <i>name [, name]</i>::
specify the name of one or more output files. If multiple
files are present, the first is used as the index.

<tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
index areas, or bit ratios of units as
they are processed.

=end

Is this a bug in rdoc?

Wybo

Morton Goldberg
Guest
Posts: n/a

 10-16-2006
On Oct 16, 2006, at 7:10 AM, Wybo Dekker wrote:

> -- The following example, is taken from the rdoc documentation.
> For the long options, it converts -- into — (a long hyphen)
> instead of two separate hyphens with some whitespace in between.
> (see www.servalys.nl/ doc/index.html for the output)
>
> =begin rdoc
>
> <tt>--output</tt> <i>name [, name]</i>::
> specify the name of one or more output files. If multiple
> files are present, the first is used as the index.
>
> <tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
> index areas, or bit ratios of units as
> they are processed.
>
> =end
>
> Is this a bug in rdoc?

No, it's a feature.

Back in the old days, when people typed on typewriters, which didn't
have an em-dash (what you call a long hyphen) key, two hyphens were
used to indicate an em-dash. Since the ASCII character set doesn't
have em-dash, this convention is carried over to rdoc.

Why does this bother you?

Regards, Morton

Jan Svitok
Guest
Posts: n/a

 10-16-2006
On 10/16/06, Morton Goldberg <(E-Mail Removed)> wrote:
> On Oct 16, 2006, at 7:10 AM, Wybo Dekker wrote:
>
> > -- The following example, is taken from the rdoc documentation.
> > For the long options, it converts -- into — (a long hyphen)
> > instead of two separate hyphens with some whitespace in between.
> > (see www.servalys.nl/ doc/index.html for the output)
> >
> > =begin rdoc
> >
> > <tt>--output</tt> <i>name [, name]</i>::
> > specify the name of one or more output files. If multiple
> > files are present, the first is used as the index.
> >
> > <tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
> > index areas, or bit ratios of units as
> > they are processed.
> >
> > =end
> >
> > Is this a bug in rdoc?

>
> No, it's a feature.
>
> Back in the old days, when people typed on typewriters, which didn't
> have an em-dash (what you call a long hyphen) key, two hyphens were
> used to indicate an em-dash. Since the ASCII character set doesn't
> have em-dash, this convention is carried over to rdoc.
>
> Why does this bother you?

Because it's not clearly visible that one must type two dashes there.
The solution would be to not convert special chars in <tt></tt> blocks
(the conversion takes place at
lib\rdoc\markup\simple_markup\to_html.rb:195)

Wybo Dekker
Guest
Posts: n/a

 10-16-2006

Jan Svitok wrote:
> On 10/16/06, Morton Goldberg <(E-Mail Removed)> wrote:
>> On Oct 16, 2006, at 7:10 AM, Wybo Dekker wrote:
>>
>> > -- The following example, is taken from the rdoc documentation.
>> > For the long options, it converts -- into — (a long hyphen)
>> > instead of two separate hyphens with some whitespace in between.
>> > (see www.servalys.nl/ doc/index.html for the output)
>> >
>> > =begin rdoc
>> >
>> > <tt>--output</tt> <i>name [, name]</i>::
>> > specify the name of one or more output files. If multiple
>> > files are present, the first is used as the index.
>> >
>> > <tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
>> > index areas, or bit ratios of units as
>> > they are processed.
>> >
>> > =end
>> >
>> > Is this a bug in rdoc?

>>
>> No, it's a feature.
>>
>> Back in the old days, when people typed on typewriters, which didn't
>> have an em-dash (what you call a long hyphen) key, two hyphens were
>> used to indicate an em-dash. Since the ASCII character set doesn't
>> have em-dash, this convention is carried over to rdoc.
>>
>> Why does this bother you?

>
> Because it's not clearly visible that one must type two dashes there.
> The solution would be to not convert special chars in <tt></tt> blocks

I agree!

> (the conversion takes place at
> lib\rdoc\markup\simple_markup\to_html.rb:195)
>

--
Wybo

Wybo Dekker
Guest
Posts: n/a

 10-17-2006
I wrote:

> The following example, is taken from the rdoc documentation.
> For the long options, it converts -- into — (a long hyphen)
> instead of two separate hyphens with some whitespace in between.
> (see www.servalys.nl/ doc/index.html for the output)
>
> =begin rdoc
>
> <tt>--output</tt> <i>name [, name]</i>::
> specify the name of one or more output files. If multiple
> files are present, the first is used as the index.
>
> <tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
> index areas, or bit ratios of units as
> they are processed.
>
> =end

now if one runs rdoc on a file containing only the range of lines
between =begin and =end, this generates html as expected. But anything
other than a shebang line in front spoils this. In this case, the
following text produces an empty html-page:

puts "this is a test"

=begin rdoc

<tt>--output</tt> <i>name [, name]</i>::
specify the name of one or more output files. If multiple
files are present, the first is used as the index.

<tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
index areas, or bit ratios of units as
they are processed.

=end

--
Wybo

Phrogz
Guest
Posts: n/a

 10-17-2006
Wybo Dekker wrote:
> now if one runs rdoc on a file containing only the range of lines
> between =begin and =end, this generates html as expected. But anything
> other than a shebang line in front spoils this. In this case, the
> following text produces an empty html-page:

Do you consider this a bug? I consider it a feature. I like being able
to have random comment blocks (with =begin...=end or many lines of #)
in my files and not have them added to the RDoc output.

Wybo Dekker
Guest
Posts: n/a

 10-17-2006
Phrogz wrote:
> Wybo Dekker wrote:
>> now if one runs rdoc on a file containing only the range of lines
>> between =begin and =end, this generates html as expected. But anything
>> other than a shebang line in front spoils this. In this case, the
>> following text produces an empty html-page:

>
> Do you consider this a bug? I consider it a feature. I like being able
> to have random comment blocks (with =begin...=end or many lines of #)
> in my files and not have them added to the RDoc output.

Sure, but the text between

=begin rdoc

and

=end

should get in the Rdoc output. What else would these directives be
useful for??

--
Wybo