bug in rdoc?

[Wybo Dekker]

-- 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]

-- 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]

-- 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]

-- 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!

 

[Wybo Dekker]

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

 

[Phrogz]

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]

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??