Asp Forum - bug in rdoc? - comp.lang.ruby

Wybo Dekker

10/16/2006 11:10:00 AM

-- 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> name [, name]::
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

4 Answers

Morton Goldberg

10/16/2006 1:56:00 PM

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> name [, name]::
> 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

Jano Svitok

10/16/2006 2:13:00 PM

On 10/16/06, Morton Goldberg <m_goldberg@ameritech.net> 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> name [, name]::
> > 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

10/16/2006 2:46:00 PM

Jan Svitok wrote:
> On 10/16/06, Morton Goldberg <m_goldberg@ameritech.net> 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> name [, name]::
>> > 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

10/17/2006 11:00:00 AM

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> name [, name]::
> 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> name [, name]::
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

comp.lang.ruby

bug in rdoc?

Wybo Dekker

Morton Goldberg

Jano Svitok

Wybo Dekker

Wybo Dekker

x Login to ForumsZone