Text
Page: 1
History of Japanese Ruby reference
manual, and future
Kazuhiro NISHIYAMA
株式会社 Ruby 開発
RubyKaigi 2022
2022-09-10
Powered by Rabbit 3.0.1
Page: 2
self.introduction
Kazuhiro NISHIYAMA
One of Ruby committers
One of owners of https://github.com/rurema
Today’s topic
Ruby Development Inc.
one of Silver Sponsors
jimlock (one of TRICK 2022 winner) is my coworker
Twitter, GitHub: @znz
1/24
Page: 3
Agenda
What is rurema?
History of Japanese Ruby reference manual
Before rurema
Recent changes
Future plans
Short term plans
Medium term plans
Long term plans
2/24
Page: 4
What is rurema (るりま)?
Japanese Ruby reference manual
Rubyリファレンスマニュアル刷新計画
https://github.com/rurema
rurema/doctree
documents
rurema/bitclust
original system
3/24
Page: 5
るりま != るびま
Rubyist Magazine
https://magazine.rubyist.net/
https://github.com/rubima
a similar name, but not related
in FAQ (rubima exist since that time)
Q. るびま、って「ネギま！」のぱくりですか？
A. 違います。多分。「るびま」を考えた人たちは「ネギま！」
を知りませんでした ( または、言われるまで気付かなかった ) 。
4/24
Page: 6
Before rurema
Before Ruby 1.4.6
https://ftp.ruby-lang.org/pub/ruby/doc/
Documents written in RD
English: ruby-man-1.4.6.tar.gz
Japanese: ruby-man-1.4.6-jp.tar.gz
(HTML files encoding is iso-2022-jp)
Ruby 1.6 to 1.8 era
Edit documents on RWiki
RWiki is a Wiki using RD + some extensions
5/24
Page: 7
Starting rurema
In Ruby 1.8 era
Started rurema (Rubyリファレンスマニュアル刷新計画)
bitclust supports RD based original syntax
bitclust does not use RDtool (https://rubygems.org/gems/rdtool)
Import documents from RWiki
6/24
Page: 8
License of documents
License exists in the edit form of RWiki with
license can be changed if there is an agreement on ML (rubyist ML on
freeml. it already removed, and freeml service ended)
License changed to Creative Commons — Attribution 3.0
Unported
https://github.com/rurema/doctree/blob/master/refm/doc/
license.rd
7/24
Page: 9
System improvements in bitclust era
Convert documents from EUC-JP to UTF-8
Support code colorize (#@samplecode)
#@ is prefix of pre-processors
Output as chm, ePub too
may not work now
if it does not work, contribution chance!
default: static html (used on docs.ruby-lang.org)
8/24
Page: 10
Project current status
Documentation improvement sub-projects
Support new versions of Ruby
https://rurema-review.connpass.com/
9/24
Page: 11
Documentation improvement sub-
projects
Add executable sample codes
https://github.com/rurema/doctree/issues/433
コピペ可能なサンプルコードを整備する
Colorize sample codes
→ stalled (maybe almost done?)
10/24
Page: 12
Support new versions of Ruby
Well supported
Method changes (new, changed arguments or functionality, removed)
Insufficient supported
Syntax changes (pattern match, &., …)
Changes are not clear where to write
11/24
Page: 13
rurema-review
https://rurema-review.connpass.com/
every Tuesday night
るりまレビュー会 → るりまもくもく会
after 鹿児島Ruby会議01
Many pull requests merged
→ inactive
12/24
Page: 14
Help wanted
Help wanted to check current statuses
Coordinator is also wanted
Contact us on GitHub issues or #rurema channel of ruby-jp slack
https://github.com/rurema/doctree/issues
https://ruby-jp.github.io/
13/24
Page: 15
Future plans
Short term plans
Medium term plans
Long term plans
14/24
Page: 16
RD based → Markdown based
Most important biggest short term plan
Markdown is more familiar for many users
It makes more contributions
I am investigating how to convert from current syntax
15/24
Page: 17
Current syntax
#@ lines are bitclust pre-processors
--- line is MethodList of RD
#@since 3.1
--- intersect?(other)
-> bool
other と共通の要素が少なくとも1個あれば true を、なければ false を返します。
#@samplecode 例
a = [ 1, 2, 3 ]
b = [ 3, 4, 5 ]
16/24
Page: 18
Convert pre-processors
Version branching, include, …
I care about
Editors support what extensions
Do not break Markdown processor which does not support extensions (e.g.
GitHub.com)
17/24
Page: 19
MethodList
What is alternative of MethodList
Current syntax is based on def m(args)
Blocks have notation fluctuations
{|x| ... }, {|x| block }, or &block
Return types are not used effectively
18/24
Page: 20
Other syntax
#@samplecode → code block
links and references → ? (thinking)
link from [[ref:m17n_prog]] to ===[a:m17n_prog] M17N プログラミングの
基本 in the same file
link from [[ref:c:GC#tuning_gc]] to ====[a:tuning_gc] チューニングのた
めの環境変数 in the other file
19/24
Page: 21
Other short term plans and problems
Clean up unused files, old files
ChangeLog, setup.rb, …
Not sure if tools are still usable
Lack of usage documentation
This is most important for contributors
Reproducible build
in container? devcontainer?
20/24
Page: 22
Medium term plans with other
software
Cooperation with RBS
e.g. Check signatures
Cooperation with IRB
Support to show rurema instead of rdoc
21/24
Page: 23
Medium term plans for documents
Executable sample code using WASM
hanachin already tried https://github.com/hanachin/bitclust/commit/
1ae60bfabd09c0d241e6966a6800e27a797ce175 and will discuss at https://
github.com/rurema/doctree/issues/2730
Clean up unbundled libraries and old documents
Some documents moved to https://github.com/rurema/historical-documents
22/24
Page: 24
Long term plans
I18n support
Hard to merge rdoc, so rurema will continue separately
gettext based?
or something else based?
It should be based on English, so unlikely to come true
23/24
Page: 25
end
Short term most important plans to increase contributions
RD based → Markdown based
Improve usage documentation
Middle term plans: Improve for users
Resolve many historical problems progressively
Contribution welcome!
Contact us on GitHub or #rurema channel of ruby-jp slack
Powered by Rabbit 3.0.1
24/24
