bug in rdoc?

Discussion in 'Ruby' started by Wybo Dekker, Oct 16, 2006.

  1. Wybo Dekker

    Wybo Dekker Guest

    -- 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
    Wybo Dekker, Oct 16, 2006
    #1
    1. Advertising

  2. 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
    Morton Goldberg, Oct 16, 2006
    #2
    1. Advertising

  3. Wybo Dekker

    Jan Svitok Guest

    On 10/16/06, Morton Goldberg <> 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)
    Jan Svitok, Oct 16, 2006
    #3
  4. Wybo Dekker

    Wybo Dekker Guest

    Jan Svitok wrote:
    > On 10/16/06, Morton Goldberg <> 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, Oct 16, 2006
    #4
  5. Wybo Dekker

    Wybo Dekker Guest

    another bug in rdoc?

    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
    Wybo Dekker, Oct 17, 2006
    #5
  6. Wybo Dekker

    Phrogz Guest

    Re: another bug in rdoc?

    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.
    Phrogz, Oct 17, 2006
    #6
  7. Wybo Dekker

    Wybo Dekker Guest

    Re: another bug in rdoc?

    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
    Wybo Dekker, Oct 17, 2006
    #7
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Andreas Schwarz
    Replies:
    6
    Views:
    241
    Randy W. Sims
    Jan 1, 2004
  2. Brian Schröder
    Replies:
    5
    Views:
    126
    Dave Thomas
    Sep 18, 2004
  3. Daniel Berger
    Replies:
    1
    Views:
    138
    Dave Thomas
    Nov 2, 2004
  4. Iwan van der Kleyn

    rdoc: how to add readme.rdoc as index.html?

    Iwan van der Kleyn, Apr 26, 2005, in forum: Ruby
    Replies:
    1
    Views:
    218
    Stefan Lang
    Apr 26, 2005
  5. Paul Van Delst

    How to use rdoc parsers outside of rdoc?

    Paul Van Delst, Jul 27, 2006, in forum: Ruby
    Replies:
    0
    Views:
    95
    Paul Van Delst
    Jul 27, 2006
Loading...

Share This Page