Feature #6388

Convert README to README.rdoc with formatting

Added by Zachary Scott over 3 years ago. Updated over 3 years ago.

[ruby-core:44784]
Status:Closed
Priority:Normal
Assignee:Eric Hodel

Description

I've moved the current README into README.rdoc and reformatted using rdoc markup. See attached patch.

0002-README-to-rdoc.patch Magnifier (9.62 KB) Zachary Scott, 05/02/2012 07:43 AM

00021-README-to-rdoc.patch Magnifier (9.62 KB) Zachary Scott, 05/02/2012 07:48 AM

0003-READMEja-to-rdoc.patch Magnifier (15.3 KB) Zachary Scott, 05/02/2012 08:52 AM

Associated revisions

Revision 35518
Added by Nobuyoshi Nakada over 3 years ago

  • README, README.ja: reformatted using rdoc markup. based on the patches by zzak (Zachary Scott) in [Feature #6388].
  • README, README.ja: updated the author's mail address.

Revision 35518
Added by Nobuyoshi Nakada over 3 years ago

  • README, README.ja: reformatted using rdoc markup. based on the patches by zzak (Zachary Scott) in [Feature #6388].
  • README, README.ja: updated the author's mail address.

History

#1 Updated by Zachary Scott over 3 years ago

Changed some of the code formatting in the rdoc markup.

#2 Updated by Zachary Scott over 3 years ago

I've added another patch to convert README.ja to rdoc.

#3 Updated by Nobuyoshi Nakada over 3 years ago

  • Tracker changed from Bug to Feature

#4 Updated by Nobuyoshi Nakada over 3 years ago

  • % Done changed from 0 to 100
  • Status changed from Open to Closed

This issue was solved with changeset r35518.
Zachary, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.


  • README, README.ja: reformatted using rdoc markup. based on the patches by zzak (Zachary Scott) in [Feature #6388].
  • README, README.ja: updated the author's mail address.

#5 Updated by Zachary Scott over 3 years ago

Hi Nobu, Thanks for the merge!

Is there a reason to remove the '.rdoc' extensions?

As you can see[1], github will only parse the markdown of the README's extension.

1: http://github.com/ruby/ruby#readme

#6 Updated by Nobuyoshi Nakada over 3 years ago

It doesn't seem necessary, because you hadn't mentioned about github at all.

Github's RDoc parser seems dealing with inline markups in multibyte contents differently than the bundled one.

#7 Updated by Nobuyoshi Nakada over 3 years ago

I'm neutral to change the names, and will rename them if no objections.
Any thoughts?

#8 Updated by Yusuke Endoh over 3 years ago

Hello,

nobu (Nobuyoshi Nakada) wrote:

I'm neutral to change the names, and will rename them if no objections.
Any thoughts?

I don't like it very much.

README is not for github, but for newbie.
README extensions often represent platform in Unix culture.
".rdoc" may confuse users familiar with Unix but unfamiliar
with Ruby's toolchain.

$ ls perl-5.14.2/README*
perl-5.14.2/README perl-5.14.2/README.hurd perl-5.14.2/README.plan9
perl-5.14.2/README.aix perl-5.14.2/README.irix perl-5.14.2/README.qnx
perl-5.14.2/README.amiga perl-5.14.2/README.jp perl-5.14.2/README.riscos
perl-5.14.2/README.beos perl-5.14.2/README.ko perl-5.14.2/README.solaris
perl-5.14.2/README.bs2000 perl-5.14.2/README.linux perl-5.14.2/README.symbian
perl-5.14.2/README.ce perl-5.14.2/README.macos perl-5.14.2/README.tru64
perl-5.14.2/README.cn perl-5.14.2/README.macosx perl-5.14.2/README.tw
perl-5.14.2/README.cygwin perl-5.14.2/README.micro perl-5.14.2/README.uts
perl-5.14.2/README.dgux perl-5.14.2/README.mpeix perl-5.14.2/README.vmesa
perl-5.14.2/README.dos perl-5.14.2/README.netware perl-5.14.2/README.vms
perl-5.14.2/README.epoc perl-5.14.2/README.openbsd perl-5.14.2/README.vos
perl-5.14.2/README.freebsd perl-5.14.2/README.os2 perl-5.14.2/README.win32
perl-5.14.2/README.haiku perl-5.14.2/README.os390
perl-5.14.2/README.hpux perl-5.14.2/README.os400

Above all, "README.rdoc" is not cool based on my subjective
impression.
It can be configurable on github side, of course?

Yusuke Endoh mame@tsg.ne.jp

#9 Updated by Eric Hodel over 3 years ago

Since github is not the primary place people go to learn about ruby I think it is OK to keep "README" with no extension.

Also available in: Atom PDF