Slide 1

Slide 1 text

History of Japanese Ruby reference manual, and future Kazuhiro NISHIYAMA 株式会社Ruby開発 RubyKaigi 2022 2022-09-10 Powered by Rabbit 3.0.1

Slide 2

Slide 2 text

self.introduction Kazuhiro NISHIYAMA One of Ruby committers One of owners of Today’s topic Ruby Development Inc. one of Silver Sponsors jimlock (one of TRICK 2022 winner) is my coworker Twitter, GitHub: @znz 1/24

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

What is rurema (るりま)? Japanese Ruby reference manual Rubyリファレンスマニュアル刷新計画 rurema/doctree documents rurema/bitclust original system 3/24

Slide 5

Slide 5 text

るりま != るびま Rubyist Magazine a similar name, but not related in FAQ (rubima exist since that time) Q. るびま、って「ネギま!」のぱくりですか? A. 違います。多分。「るびま」を考えた人たちは「ネギま!」 を知りませんでした (または、言われるまで気付かなかった)。 4/24

Slide 6

Slide 6 text

Before rurema Before Ruby 1.4.6 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

Slide 7

Slide 7 text

Starting rurema In Ruby 1.8 era Started rurema (Rubyリファレンスマニュアル刷新計画) bitclust supports RD based original syntax bitclust does not use RDtool ( Import documents from RWiki 6/24

Slide 8

Slide 8 text

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 license.rd 7/24

Slide 9

Slide 9 text

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 8/24

Slide 10

Slide 10 text

Project current status Documentation improvement sub-projects Support new versions of Ruby 9/24

Slide 11

Slide 11 text

Documentation improvement sub- projects Add executable sample codes コピペ可能なサンプルコードを整備する Colorize sample codes → stalled (maybe almost done?) 10/24

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

rurema-review every Tuesday night るりまレビュー会 → るりまもくもく会 after 鹿児島Ruby会議01 Many pull requests merged → inactive 12/24

Slide 14

Slide 14 text

Help wanted Help wanted to check current statuses Coordinator is also wanted Contact us on GitHub issues or #rurema channel of ruby-jp slack 13/24

Slide 15

Slide 15 text

Future plans Short term plans Medium term plans Long term plans 14/24

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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. 17/24

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

Medium term plans for documents Executable sample code using WASM hanachin already tried 1ae60bfabd09c0d241e6966a6800e27a797ce175 and will discuss at https:// Clean up unbundled libraries and old documents Some documents moved to 22/24

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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 24/24 Powered by Rabbit 3.0.1