フォーマットされていないコード検出器

[Discourse]

	概要	未フォーマットコード検出器は、投稿前に未フォーマットのコードを検出し、警告を表示します。
	プレビュー	Discourse Theme Creator でプレビュー
	リポジトリリンク	https://github.com/discourse/unformatted-code-detector
	Discourse テーマは初めてですか？	Discourse テーマの使い方の初心者向けガイド

このテーマコンポーネントをインストール

これは Discourse チームによってメンテナンスされている#公式のテーマコンポーネントです。#サポート、#バグ、#UX、#機能リクエストは、Meta の該当カテゴリで、適切なテーマコンポーネントタグを付けて提出できます。以下のリンクをクリックして、トピックを作成してください。

 サポート  バグ  UX  機能

機能

未フォーマットのコードを投稿するユーザーには、正しいフォーマット方法を指示する警告メッセージが表示されます。

検出の感度や HTML の検出の有無は、テーマ設定で構成可能です。

設定

名前	説明
emoji icon	未フォーマット警告モーダルのタイトルの隣に表示する絵文字アイコン。
disable at trust level	信頼レベル N 以上のユーザーに対して警告を無効化します。-1 = すべてのユーザーで有効。
sensitivity	検出アルゴリズムの感度。0 = プラグイン無効化；1 = コードのように少し見えるものすべてに対して警告。
min post length to check	検査する投稿の最小長さ（文字数）
max post length to check	検査する投稿の最大長さ（文字数）。-1 = 最大値なし。
include html	他の種類のコードに加えて HTML タグも検査します。ユーザーが投稿内でカスタム HTML を頻繁にレンダリングする必要がある場合は、無効にすることをお勧めします。

翻訳キー	デフォルト値
warning_modal.title	コードを投稿しますか？
warning_modal.content	あなたの投稿にコードやログが含まれているようです。投稿を読みやすく保つために、ツールバーの「整形済みテキスト」ボタン 、またはキーボードのバッククォート ` キーを使用して、コードをフォーマットすることを忘れないでください。例：[examples]
warning_modal.do_not_show_again	このメッセージを今後表示しない
warning_modal.fix_post	投稿を編集
warning_modal.ignore_and_post_anyway	いずれにせよ投稿

デバッグ

コードを含まない投稿に対して警告が表示された場合は、ブラウザの JS コンソールを開き、debugUnformattedCodeDetector() と入力して Enter を押すことで、デバッグ情報を出力できます。これにより、どの行が「コード」と見なされたか、感度設定がどうなっているかに関する情報が表示されます。

「このメッセージを今後表示しない」は、ユーザー単位ではなく、デバイス単位でのみ機能します。これは既知の問題であり、Discourse がテーマからユーザー情報を取得する機能を備えた時点で修正されます。

当方でホストされていますか？ テーマコンポーネントは、Standard、Business、Enterprise プランで利用可能です。

[robbiet480 (Robbie Trencheny)]

We at the Home Assistant forums think that this is the best thing invented since sliced bread. Or maybe Home Assistant. Thank you so so much @lionel-rowe!!!

Two minor request:

• I don’t want to allow users to skip formatting or disable the dialog in the future. I want them to feel pain until they change their ways. I’m sadistic like that. Can you make the “Don’t show this message again” and “Post anyway” buttons optional? For now I’ve hid them with some CSS but would be better to just not include the HTML at all.

• Unsure if you are doing language detection or not, but if you are, can you add the estimated language name after the first code fence so that users will properly syntax highlight too?

Thanks so much!!

[lionel-rowe]

@robbiet480

I don’t want to allow users to skip formatting or disable the dialog in the future. I want them to feel pain until they change their ways. I’m sadistic like that. Can you make the “Don’t show this message again” and “Post anyway” buttons optional? For now I’ve hid them with some CSS but would be better to just not include the HTML at all.

I wouldn’t recommend hiding them, especially if you leave the setting to include HTML detection on. Power users may still want to have their (sanitized) HTML parsed as such, not formatted as code. Two examples where this can be useful are kbd and abbr tags.

If you exclude HTML tags from detection (which may be viable depending on the scope of your forum), hiding the “don’t show this again” would probably be OK. I still wouldn’t recommend hiding the “post anyway”, though, because there are bound to still be some edge cases of false positives (I hit one the other day where I’d omitted a space before an opening parenthesis — poor typesetting, but not unformatted code). Then you’ll have a situation where users can’t post their question at all, and, unless they report the issue to you directly, you won’t even know about it.

@robbiet480

Unsure if you are doing language detection or not, but if you are, can you add the estimated language name after the first code fence so that users will properly syntax highlight too?

Language detection is beyond the scope of this component, I’m afraid. Where possible, it looks for syntactical features shared by many languages, such as lines ending in semicolons, certain configurations of curly braces, and so on.

I am thinking about ways to enhance the UX, though. One big improvement would be to make it much more interactive. For example, instead of a simple modal, the user would be presented with a wizard that first asks them which language their post concerns (select from a dropdown), then a screen which asks them to select which ranges of their post are code (defaulting to lines that contain strings flagged by the plugin), then generating the appropriate markdown. This would still include a “skip and post anyway” option, though, for the reasons I mentioned.

I don’t have a timeline for this change, but it’d be good to know if it’s something people would be interested in.

[robbiet480 (Robbie Trencheny)]

Already hit the edge cases issue within 30 minutes or so of hiding the elements, so they have been re-added.

I would be super interested in the modal being more interactive!

[codinghorror (Jeff Atwood)]

一点だけお知らせです。このコンポーネントは近日中に正式化され、@lionel-rowe と @david と密に連携して進めてまいります。アイデアやフィードバックがあれば、今が共有するタイミングです！

[tpetrov (Toni Petrov)]

@codinghorror

簡単なご連絡ですが、まもなくこのコンポーネントを正式化し、@lionel-rowe と @david と緊密に連携して実現に向けて取り組む予定です。アイデアやフィードバックがあれば、今が共有するタイミングです！

素晴らしいニュースですね！

意味があるかどうかわかりませんが、フォーマットを壊す最も一般的な Markdown の間違いについてもアラートを出せるようになると大変助かります。

[tpetrov (Toni Petrov)]

また、フォーマットされていないと疑われるコードの場所を示すヒントがあるとさらに良いと思います。

私はちょうど別の返信を書いていたところ、コードを貼り付けていないにもかかわらずアラートが表示されました。しばらくして、topic_id という単語を使ったことが原因だと気づきました。しかし、この単語がコードだと検出器が判断していることは明らかではなく（大多数の人もそうは思わないでしょう）、私見ではそう思います。

単語にアンダースコアが含まれているからといって、必ずしもコードであるとは限らないと思います。

[lionel-rowe]

これまでのご意見、ありがとうございます！検出の感度が高すぎるのを軽減するため、いくつかの設定を追加・調整する予定です。

@tpetrov 一点だけ追加で質問です。ポップアップの文言は、コードが含まれていないと思う場合は無視して投稿してもよいことが明確に伝わる内容になっていますか？それとも、認識された問題を「修正」しなければならないかのような強制感があるように感じられますか？

[tpetrov (Toni Petrov)]

私の懸念は、多くの人がそれを読み通さないことです。
現在、複数の文を含むポップアップが表示されると、人々はテキストを無視して「OK」ボタン（クッキー、利用規約などに同意するボタン）を探す傾向があります。

それでも、「投稿に未フォーマットのコードが含まれている可能性があります」という表現を「投稿にコードを使用していますか？」に変えるのはどうでしょうか。質問形式の方が注目を集めやすいからです。

私は UX の専門家ではありませんが、このボタンは少し強引に感じます：

クリックしたくないようなボタンです。もちろん、これが意図するところであり、人々が投稿をより適切にフォーマットしようとするのではなく、単にスキップしてしまうことを防ぐためです。

[mbauman (Matt Bauman)]

おっと、このアイデアいいですね…でも、ちょうど誤検知が起きてしまいました：

Discobot tutorial generating modmail

It’s still early for our relatively small site but this is looking promising. In the month prior to changing this, 18 folks did that tutorial step and 4 flagged it wrong. In the month+ since 17 have done that step and 0 got it wrong. The new text adds a few more details about why you might flag a post but I’m guessing it’s the very small change to the final sentence that’s doing most of the work: We like our discussions friendly, and we need your help to keep things civilized. If you see a…

壊れたリンクが原因だったのかもしれませんね？それらはテンプレートエンジンから取得されたもので、[keep things civilized](%{guidelines_url}) のような形式になっています。あるいは HTML の img タグが原因でしょうか？

[lionel-rowe]

@tpetrov

それでも、「投稿に未フォーマットのコードが含まれている可能性があります」という表現を「投稿にコードを使用していますか？」に変更するのはどうでしょうか。時には質問形式の方が注目を集めやすいですから。

悪くないアイデアですね、@david。モーダルのタイトルを「コードスニペットを投稿していますか？」に変更してみましょうか。

@tpetrov

UX の専門家ではありませんが、このボタンは少し過剰なほど強力に見えます：
- 誰でもクリックしたくないようなデザインです。もちろん、それが狙いなのでしょう。人々が投稿をより適切にフォーマットするのではなく、単にこのボタンを無視しないようにするためです。

おそらくその通りでしょう。次のバージョンでは、これを標準的なグレーのボタンに変更します。

@mbauman

壊れたリンクが原因だったのかもしれませんか？それらはテンプレートエンジンから取得されたもので、[keep things civilized](%{guidelines_url}) のような形式になっています。あるいは HTML の img タグでしょうか？

実は、両方が原因でした！デフォルト設定の次のバージョンでは、この投稿ではトリガーされなくなります。

[codinghorror (Jeff Atwood)]

新しいコピーの展開を開始し、コンポーネント用のポジティブおよびネガティブなテストサンプル投稿のコーパスを構築しています。順調に進んでいますので、今しばらくお待ちください！

[tmomas]

@codinghorror

アイデアやフィードバックがあれば、今こそ共有してください！

小さな指摘ですが：warning_modal.content のデフォルトでは「code」ツールバーボタンを求めています。しかし、このボタンはエディタでマウスを合わせると「Preformatted text」ボタンと呼ばれています。

新しいユーザーがこのボタンを見つけやすくするため（彼らは「code」ボタンを見つけることはできません）、warning_modal.content を「code button」から「Preformatted text button」に変更する必要があります。

[tmomas]

トピックにさらに例と手順を示すリンクを追加するにはどうすればよいですか？

単純に warning_modal.content の末尾に追加しようとしましたが、その結果は以下のようになりました（私の追加部分は黄色でマークしています）：

現在のコンテンツの下にテキストとリンクを追加するにはどうすればよいでしょうか？

編集：

warning_modal.content の文字を 1 文字変更するだけで、フォーマットが壊れてしまうことに気づきました。

さらに酷いことに、warning_modal.content 入力フィールドをクリックして矢印キーでカーソルを移動するだけで、入力フィールドがハイライト表示されてしまいます。「編集済み」の warning_modal.content を保存するために緑色のチェックマークをクリックしても（実際には変更は行われておらず、カーソルを 1 文字移動しただけですが）、上記のようにフォーマットが壊れてしまいます。

編集 #2

https://meta.stackexchange.com/questions/82718/how-do-i-escape-a-backtick-within-in-line-code-in-markdown の助けを借りて解決しました。

@codinghorror @lionel-rowe について、デフォルトの warning_modal.content の設定を見直し、スペースとバッククォート（バッククォートで囲まれた「multiplelines」セクション内の欠落したスペースが上記の問題を引き起こしていました）の調整を検討していただけないでしょうか。

[tmomas]

ユーザーが手動で（ボタンを使わずに）コードフェンスのキーを選択する際、どのキーを選ぶべきかをより明確に伝える方法はありませんか？

今日、以下のような事例がありました：

ユーザーは明らかに指示に従おうとしたものの、コードフェンスのキーを誤って選択しました（` の代わりに ' を使用）。過去にも、``` の代わりに ... が使われる事例を目にしました。これらのケースはいずれも、ユーザーがどのキーを選ぶべきかについて、より明確な指示を必要としていることを示しています。

あるいは、これらのキーでユーザーを混乱させず、「『整形済みテキスト』ボタンを使用すれば完了です」とだけ伝えるという方法もあります。

---

@lionel-rowe 検出動作をカスタマイズするにはどうすればよいですか？

現在、shebang はコードとして検出されていませんが、これを変更したいと考えています。

期待される動作：#! はスクリプトの開始を示すため、コードとして検出されるべきです。

検出されない例：

---

#!/bin/sh

echo “test”

. /lib/upgrade/common.sh

firmware=“/tmp/firmware.img”
tmpdir=“/tmp/_upgrade”
output=“/dev/ttyS0”
before=“before-upgrade.sh”
after=“after-upgrade.sh”

---

これに加えて、root@ もコードとして検出されると我々にとって有用です。

root@OpenWrt:~# ip link add link eth0 name eth0.9 type vlan id 9
root@OpenWrt:~# brctl addbr br-foo
root@OpenWrt:~# brctl addif br-foo eth0.9
root@OpenWrt:~# ip link set eth0.9 up
root@OpenWrt:~# ip link set br-foo up

[codinghorror (Jeff Atwood)]

@tmomas

これに加えて、root@ がコードとして検出されるようにしてくださると、私たちにとって非常に役立ちます。

@david 検出をカスタマイズする方法はありますか？

[david (David Taylor)]

現時点では、サイトごとのカスタマイズを行う方法は存在しません。ただし、「コードエナジー」システムにシェバンやシェルプロンプトの検出機能を追加することは検討可能です。

[david (David Taylor)]

@tmomas

warning_modal.content 入力フィールドをクリックし、矢印キーでカーソルを移動すると、入力フィールドが強調表示されます。その後、「編集済み」と表示された warning_modal.content を保存するために緑色のチェックマークをクリックすると（実際には変更を加えず、カーソルを 1 文字移動しただけですが）、上記のようにフォーマットが壊れてしまいます。

ご報告ありがとうございます。これはマルチラインのテーマ翻訳に関するコアなバグのようです。修正のための PR を作成しました：

FIX: Use <textarea> for theme translations (#14322)

[hhlp]

Discourse サイトの多くはトラブルシューティングツールとして Discourse を利用しています。このプラグインは、コードだけでなく、以下のタスクにも適していますか？

Linux:

• ログ
• Linux コマンドライン（CLI）
• ターミナル出力

例：

Sensors:
  System Temperatures: cpu: 78.0 C mobo: 36.0 C gpu: nouveau temp: 56.0 C 
  Fan Speeds (RPM): cpu: 0 fan-1: 3139 fan-3: 0 fan-5: 0 
  Power: 12v: N/A 5v: 2.90 3.3v: N/A vbat: 3.34 

よろしくお願いいたします。