OSS Gate Workshop: online: 2023-09-30: SuzukaHori: htmlbeautifier: Work log

[SuzukaHori]

This is a work log of a "OSS Gate workshop".
"OSS Gate workshop" is an activity to increase OSS developers.
Here's been discussed in Japanese. Thanks.

作業ログ作成時の説明

以下のテンプレートを埋めてタイトルに設定します。埋め方例はスクロールすると見えてきます。

OSS Gate Workshop: ${LOCATION}: ${YEAR}-${MONTH}-${DAY}: ${ACCOUNT_NAME}: ${OSS_NAME}: Work log

タイトル例↓：

OSS Gate Workshop: Tokyo: 2017-01-16: kou: Rabbit: Work log

OSS Gateワークショップ関連情報

• スライド：ワークショップの進行に使っているスライドがあります。
• チャット：OSS開発に関することならなんでも相談できます。ワークショップが終わった後もオンラインで相談しながら継続的にOSSの開発に参加しましょう！
• シナリオ：ワークショップの目的・内容・進め方の詳細が書いています。
• 過去のビギナーの作業ログ：他の人の作業ログから学べることがいろいろあるはずです。

[SuzukaHori]

作業メモを作りました。

[SuzukaHori]

Github:https://github.com/threedaymonk/htmlbeautifier
ライセンス：https://github.com/threedaymonk/htmlbeautifier/blob/master/COPYING.txt

[SuzukaHori]

機能を触ってみる。

or to operate on standard input and output:

$ htmlbeautifier < input > output

この部分のやり方がわからない

[SuzukaHori]

学び：自分が実行しているコマンドが何の機能で提供されている物なのか、ちゃんと理解する。
似た名前の他のソフトウェアだと混同して、ずっと違うリポジトリを見ていた。

[SuzukaHori]

コマンドの引数にディレクトリが入れられると便利。
現状だとエラーになる。

❯ htmlbeautifier app/views                        
/Users/suzuka/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/htmlbeautifier-1.4.2/bin/htmlbeautifier:97:in `read': Is a directory @ io_fread - app/views (Errno::EISDIR)
        from /Users/suzuka/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/htmlbeautifier-1.4.2/bin/htmlbeautifier:97:in `block in <top (required)>'
        from /Users/suzuka/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/htmlbeautifier-1.4.2/bin/htmlbeautifier:96:in `each'
        from /Users/suzuka/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/htmlbeautifier-1.4.2/bin/htmlbeautifier:96:in `<top (required)>'
        from /Users/suzuka/.rbenv/versions/3.2.2/bin/htmlbeautifier:25:in `load'
        from /Users/suzuka/.rbenv/versions/3.2.2/bin/htmlbeautifier:25:in `<main>'

/Users/suzuka/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/htmlbeautifier-1.4.2/bin/htmlbeautifierを書き換えてディレクトリを指定できるようにして使ってた。

書き換え前

書き換え後

# 89行目
if ARGV.any?
  failures = []
  #ここから追記
  if FileTest.directory?(File.open(ARGV[0]))
    dir = ARGV[0]
    files = Dir.entries(dir).select{ |file| File.extname(file) == ".erb"}
    ARGV.replace(files.map{|file| dir +"/"+ file })
  end
  #ここまで
  ARGV.each do |path|
    input = File.read(path)
    if options[:lint_only]
      output = StringIO.new
      beautify path, input, output, options
      failures << path unless input == output.string
    else
      temppath = "#{path}.tmp"
      File.open(temppath, "w") do |file|
        beautify path, input, file, options
      end
      FileUtils.mv temppath, path
    end
  end
  unless failures.empty?
    $stderr.puts [
      "Lint failed - files would be modified:",
      *failures
    ].join("\n")
    exit 1
  end
else
  beautify "standard input", $stdin.read, $stdout, options
end

[SuzukaHori]

機能を触ってみる。

or to operate on standard input and output:

$ htmlbeautifier < input > output

この部分のやり方がわからない

$ htmlbeautifier 整形したいファイル名  出力したいファイル名

これでやってみたができなかった。（ファイルが空になる。）
ググっても情報なし。

[SuzukaHori]

input output問題について

chatGPTに聞いた。

[SuzukaHori]

アドバイスいただいた。
htmlbeautifier input > &output

[SuzukaHori]

このコマンドでもoutput.txt が空になる。（フォーマットはできている。）
htmlbeautifier input.html.erb >&output.txt

[SuzukaHori]

これだと何も起きない（フォーマットもできない）

❯ htmlbeautifier &input.html.erb > output.txt
[5]  + suspended (tty input)  htmlbeautifier

[SuzukaHori]

<>を勝手に省略してしまっていたのが原因！

$ htmlbeautifier < フォーマットするファイル名 > 出力するファイル名

[SuzukaHori]

日本語でのまとめ

--

READMEの説明について

以下の箇所のinputとoutputが何を指すのかが理解できなかった。

or to operate on standard input and output:

$ htmlbeautifier < input > output

加えて、誤ってコマンドを実行して、フォーマットできずに困った。

$ htmlbeautifier input_file_name output_file_name

inputとoutputがファイルを指すという明記し、また<>を省略するではないと明記するべき。

期待値：READ MEを読んだ初心者が適切にgemを活用できること。

[SuzukaHori]

コミットメッセージの作り方

https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
最初の行は大文字で始まり、命令形を使用し、50 文字以内で、ピリオドで終わってはいけない。

[SuzukaHori]

READMEのinput outputの内容

gemを作ってくれてありがとう。

以下の部分の理解に苦慮しました。

or to operate on standard input and output:

$ htmlbeautifier < input > output

standard input and outputが何を指すのか明記してあると助かります。

フォーマットしたいファイルと出力したいファイルを指定して実行できます。

$ htmlbeautifier < update_file_name > output_file_name
※<>は省略しない

[SuzukaHori]

英訳

README: Input and Output Content

Thank you for creating the gem.

I had difficulty understanding the following part:

or to operate on standard input and output:

$ htmlbeautifier < input > output

It would be helpful if you specify what "standard input" and "output" refer to.

You can specify the file you want to format and the file you want to output to when executing.

$ htmlbeautifier < update_file_name > output_file_name

Do not omit the `<>`.

[piroor]

$ htmlbeautifier < input > output

を

$ htmlbeautifier <input> output

と誤読していたとのこと

[piroor]

$ htmlbeautifier <input_file_name >output_file_name

$ htmlbeautifier <index.erb >index_formatted.erb
$ htmlbeautifier < index.erb > index_formatted.erb

こうだと分かりやすそう

[piroor]

htmlbeautifier を使う人全員がUNIXのコマンド操作の「常識」に詳しいわけではないので、 #1672 (comment) のような誤読が発生することは多分あると思います。
他方、UNIXの常識に属することをこのプロジェクトのREADMEで丁寧に書くと、詳しい人が見たときに違和感が生まれるというのも、事実だと思います。

なので、

$ htmlbeautifier < index.erb > index_formatted.erb

のような実例も併記するように提案するというのは、「あまり詳しくない人も誤読しにくい」「詳しい人が見たときにも邪魔にならない」というバランスをとった落とし所になるんじゃないかなあと思いました！

[SuzukaHori]

@piroor
アドバイスいただきありがとうございます🙇‍♀️

他方、UNIXの常識に属することをこのプロジェクトのREADMEで丁寧に書くと、詳しい人が見たときに違和感が生まれるというのも、事実だと思います。

詳しい方も違和感のないように書く必要があるのですね！大変勉強になりました。
ファイル名の例を追記するような方向で書きたいと思います。

[github-actions]

おつかれさまでした！

ワークショップの終了にともないissueを閉じますが、このまま作業メモとして使っても構いません 👌

ワークショップの感想を集めています！

ブログなどに書かれた際は、このページへリンクの追加をお願いします 🙏

またの参加をお待ちしています！

[SuzukaHori]

日本語メモ

READMEのinput outputの内容

READMEの以下の箇所が理解できず、詰まってしまいました。

or to operate on standard input and output:

$ htmlbeautifier < input > output

原因は、私がUNIX操作に慣れていないため、<input>をファイル名として置き換えるのだと誤解して、以下のように<>を省略したコマンドを実行してしまったことです。

htmlbeautifier index.erb index_formatted.erb

以下のように、具体例を挙げて書くとわかりやすいです。

README.md
or to operate on standard input and output:
- $ htmlbeautifier < input > output
+ $ htmlbeautifier < index.erb > index_formatted.erb

[SuzukaHori]

英訳

Add example to the input and output contents of the README

I had difficulty understanding the following section in the README:

or to operate on standard input and output:

$ htmlbeautifier < input > output

The reason was that, I misunderstood that <input> should be directly replaced with a file name, and executed the command without the <> as shown below:

htmlbeautifier index.erb index_formatted.erb

For clarity, it would be helpful to provide a concrete example in the README like:

or to operate on standard input and output:
$ htmlbeautifier < input > output
+
+ example
+
+ $ htmlbeautifier < index.erb > index_formatted.erb

[SuzukaHori]

フィードバック先：https://github.com/threedaymonk/htmlbeautifier
ブランチ名：add_example_to_README
コミットメッセージ：Add example to the input and output contents of the README

→完了した
https://github.com/threedaymonk/htmlbeautifier/pull/76/files

[komagata]

@SuzukaHori PRから2週間経っているのでメインのコントリビューターの人にメンションして、「こちらいかがでしょうか？」みたいなコメントしちゃってもいいかもです〜。

[komagata]

@SuzukaHori こちらその後いかがでしょうか〜

[SuzukaHori]

@komagata
お返事が遅れ申し訳ありません。
htmlbeautifierのgemの更新が一年半前に止まっているため、現時点ではメンションすることは考えていないです🙇‍♀️（OSS Gateの際には、サポートメンターさんにしばらく更新されていない旨を相談した上で取り組んでおりました。）

気にかけていただき、ありがとうございます🙇‍♀️

[komagata]

@SuzukaHori あら、一年半前というのはそんなに古い方ではないですし、メンションはそんなに身構えなくても送っちゃっていいと思いますよ〜。
（他の方も大体がメンションで催促してかなりマージされております〜）

[SuzukaHori]

@komagata
一年半前は古くないんですね！誤解していました。
メンションを送りました🙇‍♀️

[komagata]

@SuzukaHori いい感じだと思います〜！
日本のノリと違って催促がないと重要じゃないんだなと判断されたりするので全然メンションを送るのは大丈夫だと思います。

[kou]

そうですね。メンションして問題ないです。
いろんなOSSをメンテナンスしている私の視点だと、「後で見るかー」と思ったまま忘れてしまっていることもあるので、メンションしてもらえると、「あ、忘れてたわ」と気づけて助かることがあります。
メンションを見逃すこともあるので、「メンションしたのにリアクションがない！ムキー！」みたいにならないでいてくれるとメンテナンスしている側としてはうれしいです！

[SuzukaHori]

@komagata @kou
アドバイスありがとうございます🙏
皆さん忙しくされているので、ある程度主張しないと忘れられてしまうことがあるんですね。今後はあまり気にしないでメンションしたいと思います。
そしてお返事がなくても気にしないようにします！