GitHubじゃ!Pythonじゃ!

GitHubからPython関係の優良リポジトリを探したかったのじゃー、でも英語は出来ないから日本語で読むのじゃー、英語社会世知辛いのじゃー

commonmark

CommonMark – CommonMark仕様、C言語とJavaScriptのリファレンス実装

投稿日:

CommonMark仕様、C言語とJavaScriptのリファレンス実装 http://commonmark.org

コモンマーク

CommonMarkは、Markdown構文の合理化されたバージョンであり、CおよびJavaScriptの仕様およびBSDライセンスのリファレンス実装を備えています。

やってみよう!

詳細については、 http://commonmark.orgを参照してください

このリポジトリには、仕様に対するテストの実行、および仕様のHTMLバージョンとPDFバージョンの作成用ツールとともに、仕様自体が含まれています。

リファレンス実装は、別々のリポジトリにあります。

サードパーティの図書館の一覧は、 ここでは十数種類の言語に分かれています

仕様に対するテストの実行

仕様には、コンフォーマンステストとして機能する500を超える埋め込みサンプルが含まれています。 実行可能な$PROGを使用してテストを実行するには、次のようにします。

python3 test/spec_tests.py --program $PROG

テストを実際に実行することなく、仕様から生のテストデータを抽出する場合は、次のようにします。

python3 test/spec_tests.py --dump-tests

すべてのテストをJSON形式で取得します。

スペック

specのソースはspec.txtです。 これは基本的にMarkdownファイルであり、コード例は省略形で書かれています。

```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````

スペックのHTML版を作成するにはmake spec.htmlます。 PDF版を作成するにはmake spec.pdf どちらのバージョンでも、luaロックlcmarkインストールされている必要がありますlcmark luaのロックをインストールした後、 luarocks install lcmark PDFの場合は、xelatexもインストールする必要があります。

仕様は、コンピュータの読者ではなく、人間の作家の視点から書かれています。 これはアルゴリズムではなく、コンピュータプログラムの英語翻訳ですが、ブロッククォート、コードブロック、およびMarkdownドキュメントを構成できるその他の構造要素としてカウントされるものの宣言的な記述です。

John Gruberの標準的な構文記述構文の多くの側面を未定にしているので、正確な仕様を書くには多くの決定をする必要があり、その多くは幾分恣意的です。 それらを作成する際に、既存の慣習やシンプルさ、可読性、表現力、一貫性に関する考慮事項にアピールしました。 Markdownの多くの互換性のない既存の実装における「通常の」ドキュメントは、著者が意図したとおりにできる限りレンダリングするようにしました。 そして、私たちは、さまざまな要素のルールを調和させるように努めました。 異なる意思決定が行われる可能性のある場所(例えば、リストインデントを支配するルール)では、選択肢の根拠について説明しました。 いくつかのケースでは、Markdownの目的をその記述で述べられていると考えている点で、正規の構文記述から少し離れています。

ほとんどの場合、脚注や定義リストのような拡張子を避けて、Gruberの正規の構文記述に記述されている基本要素に自分自身を限定しています。 このようなことを考える前に、コアを得ることが重要です。 ただし、改行と分離コードブロックの表示構文は含まれています。

元のマークダウンとの違い

この仕様で標準的な構文記述と矛盾するものがいくつか挙げられます:

  • Markdownで特別な意味を持つシンボルだけでなく、すべての句読記号をバックスラッシュでエスケープすることができます。 私たちは、どのシンボルがエスケープできるのかを覚えておくのは難しいことを発見しました。

  • これは、改行の2つのスペースを補完する、改行の代わりに改行、改行の末尾にバックスラッシュを追加する構文を導入しています。 これは、2空間規則の「見えない」性質に関する永続的な苦情によって動機づけられる。

  • リンク構文は(後方互換性のある方法で)もう少し予測可能になりました。 たとえば、 Markdown.plでは、インラインリンクのタイトルを一重引用符で囲むことができますが、参照リンクは使用できません。 この種の違いは、ユーザーが覚えているのが難しいため、仕様では両方のコンテキストで一重引用符を使用できます。

  • HTMLブロックのルールは異なりますが、ほとんどの場合、違いはありません。 (詳細については、HTMLブロックのセクションを参照してください)。仕様の提案により、HTMLブロックレベルタグ内にMarkdownを簡単に組み込むことができます。ただし、これを除外することもできます。 また、解析がはるかに簡単になり、高価なバックトラックを避けることができます。

  • 隣接する鳥のブロックを1つのブロッククォートに崩壊させません:

    > this is two
    
    > blockquotes
    
    > this is a single
    >
    > blockquote with two paragraphs
    
  • ただし、リスト内のコンテンツのルールはいくつかの点で異なります(HTMLブロックと同様に)。既存のドキュメントのほとんどのリストは意図したとおりにレンダリングする必要があります。 モチベーションと名づけられたリスト項目のサブセクションにおける選択肢の点と相違点については、いくつかの議論があります。 仕様の提案は、人間の作家や読者が直感的に理解できるように、レンダリングの既存の実装よりも優れていると考えています。 (ほとんどすべての既存の実装が曖昧になるような、完全に自然に見えるリストの例を多数与えることができます)。

  • 箇条書き文字を変更したり、箇条書きから番号に変更したり、またはその逆に変更すると、新しいリストが開始されます。 私たちはそれがほとんど常にライターの意図になると思っています。

  • 順序付きリスト項目を始める番号の後には、いずれかが続きます. または) 区切り文字スタイルを変更すると、新しいリストが開始されます。

  • 順序付きリストの開始番号は重要です。

  • フェンスされたコードブロックはバッククォート( ``` )またはティルダ( ~~~ )で区切られています。

貢献する

CommonMarkを議論するフォーラムがあります。 あなたはgithubの問題の代わりにそれを使って、質問や自由に議論をすることができます。 github issue trackerは、シンプルで明確で実用的な問題にのみ使用してください。

著者

仕様はJohn MacFarlaneによって書かれ、

  • 正規表現の置換( pandoc )に基づかない最初のMarkdownパーサーやPEG文法( peg- markdownlunamark )に基づく最初のマークダウンパーサーを含むいくつかの言語でのMarkdown実装の作成と管理経験は、
  • BabelMark 2を使用した既存のMarkdown実装の違いの詳細な調査、
  • David Greenspan、Jeff Atwood、Vicent Marti、Neil Williams、Benjamin Dumke-von der Eheとの幅広い議論が行われました。

最初の発表以来、多くの人々がアイデアを寄稿してきました。 KārlisGaņģisは、特に強調、強調、リンク、イメージのルールを洗練するのに役立ちました。







-commonmark

執筆者: