Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 11012] ファイルの概要

このコミットは、Go言語の公式ドキュメントの一部である記事テンプレートに、自動生成されたファイルであることを示すマーカーを追加するものです。具体的には、tmpltohtmlツールによって生成されるHTMLファイルが手動で編集されることを防ぐための{{donotedit}}というディレクティブがテンプレートファイルに追加され、それに対応するコメントが生成されたHTMLファイルに挿入されています。

コミット

commit e4d624b04d833c194dd70df1c20318fe90472278
Author: Olivier Duperray <duperray.olivier@gmail.com>
Date:   Tue Jan 3 11:40:58 2012 +1100

    doc/articles: add {{donotedit}} to templates
    
    R=golang-dev, adg
    CC=golang-dev
    https://golang.org/cl/5502088

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/e4d624b04d833c194dd70df1c20318fe90472278

元コミット内容

doc/articles: add {{donotedit}} to templates

R=golang-dev, adg
CC=golang-dev
https://golang.org/cl/5502088

変更の背景

Go言語のドキュメントは、多くの場合、テンプレートファイル（.tmpl拡張子を持つファイル）からHTMLファイル（.html拡張子を持つファイル）を自動生成する仕組みを採用しています。この自動生成プロセスは、tmpltohtmlのようなツールによって行われます。

このような自動生成されたファイルは、通常、手動で編集すべきではありません。なぜなら、手動で加えた変更は、次にテンプレートからHTMLが生成された際に上書きされてしまうためです。しかし、ファイルを見ただけでは、それが手動で編集してよいファイルなのか、それとも自動生成されたものなのかが判別しにくい場合があります。

このコミットの背景には、このような混乱を防ぎ、開発者が誤って自動生成されたHTMLファイルを直接編集してしまうことを避ける目的があります。テンプレートに特定のマーカーを追加することで、生成されるHTMLファイルにもその情報が反映され、ファイルが自動生成されたものであることを明確に示せるようになります。

前提知識の解説

Go言語のドキュメント生成プロセス

Go言語の公式ドキュメントやウェブサイトのコンテンツは、多くの場合、Goのtext/templateパッケージに似たテンプレートエンジンを使用して生成されます。これにより、共通のレイアウトやスタイルを適用しつつ、動的なコンテンツや構造化された情報を効率的に管理できます。

  • テンプレートファイル (.tmpl): これらは、最終的なHTMLコンテンツの構造と、プレースホルダー（例: {{.Title}}）を含むファイルです。これらのプレースホルダーは、データが注入される場所を示します。
  • tmpltohtmlツール: これは、Goプロジェクト内で使用されるカスタムツールであると推測されます。その役割は、.tmplファイルと、それに適用するデータ（もしあれば）を読み込み、最終的なHTMLファイル（.html）を生成することです。このツールは、ビルドプロセスの一部として実行され、ドキュメントのHTMLバージョンを最新の状態に保ちます。

<!-- ... --> (HTMLコメント)

HTMLにおける<!-- ... -->はコメントブロックを定義します。このブロック内のテキストはブラウザによってレンダリングされず、ウェブページには表示されません。主に、コードの説明、デバッグ情報、または開発者向けのメモを記述するために使用されます。このコミットでは、自動生成されたファイルであることを示すメッセージをHTMLコメントとして挿入しています。

{{...}} (Goテンプレートの構文)

Goのtext/templateパッケージでは、{{と}}で囲まれた部分がテンプレートアクションとして解釈されます。これらは、変数、関数呼び出し、制御構造（if、rangeなど）などを埋め込むために使用されます。このコミットで追加された{{donotedit}}は、おそらくtmpltohtmlツールが特別に解釈するカスタムディレクティブ、または単にテンプレート内で使用されるプレースホルダーであり、ツールがこれを特定のHTMLコメントに変換するように設定されていると考えられます。

技術的詳細

この変更の技術的な核心は、ドキュメント生成ワークフローにおける「ソース・オブ・トゥルース（唯一の信頼できる情報源）」を明確にすることにあります。

  1. テンプレートへのマーカー追加: doc/articles/defer_panic_recover.tmpl と doc/articles/error_handling.tmpl の両方に {{donotedit}} という文字列が追加されています。これは、Goのテンプレートエンジンが処理する特殊なディレクティブまたはプレースホルダーとして機能します。

  2. HTML生成時の変換: tmpltohtmlツールは、これらのテンプレートファイルを処理する際に、{{donotedit}}ディレクティブを特定のHTMLコメントに変換するように設定されています。具体的には、以下のコメントが生成されたHTMLファイルに挿入されます。

    <!--
  DO NOT EDIT: created by
    tmpltohtml articles/defer_panic_recover.tmpl
-->

    または

    <!--
  DO NOT EDIT: created by
    tmpltohtml articles/error_handling.tmpl
-->

    このコメントは、そのHTMLファイルが手動で編集されるべきではなく、対応する.tmplファイルからtmpltohtmlツールによって生成されたものであることを明示しています。

  3. 目的:

    • 開発者の誤操作防止: 開発者が誤って自動生成されたHTMLファイルを直接編集し、その変更が後のビルドで失われるのを防ぎます。
    • ワークフローの明確化: ドキュメントのソースが.tmplファイルであり、.htmlファイルは派生品であることを明確にします。
    • メンテナンス性の向上: ドキュメントの変更は常にテンプレートファイルに対して行われるべきであるというルールを強制し、一貫性を保ちます。

このアプローチは、ビルドシステムやコード生成ツールが関与するプロジェクトで一般的に採用されるベストプラクティスです。

コアとなるコードの変更箇所

このコミットでは、以下の4つのファイルが変更されています。

  1. doc/articles/defer_panic_recover.html
  2. doc/articles/defer_panic_recover.tmpl
  3. doc/articles/error_handling.html
  4. doc/articles/error_handling.tmpl

それぞれのファイルにおける具体的な変更は以下の通りです。

diff --git a/doc/articles/defer_panic_recover.html b/doc/articles/defer_panic_recover.html
index 06f7685d48..86144fdc2c 100644
--- a/doc/articles/defer_panic_recover.html
+++ b/doc/articles/defer_panic_recover.html
@@ -1,4 +1,8 @@
 <!-- Defer, Panic, and Recover -->
+<!--
+  DO NOT EDIT: created by
+    tmpltohtml articles/defer_panic_recover.tmpl
+-->
 
 <p>
 Go has the usual mechanisms for control flow: if, for, switch, goto.  It also
diff --git a/doc/articles/defer_panic_recover.tmpl b/doc/articles/defer_panic_recover.tmpl
index 90c2b95c09..780040a7d8 100644
--- a/doc/articles/defer_panic_recover.tmpl
+++ b/doc/articles/defer_panic_recover.tmpl
@@ -1,5 +1,5 @@
 <!-- Defer, Panic, and Recover -->
-
+{{donotedit}}
 <p>
 Go has the usual mechanisms for control flow: if, for, switch, goto.  It also
 has the go statement to run code in a separate goroutine.  Here I'd like to
diff --git a/doc/articles/error_handling.html b/doc/articles/error_handling.html
index 1a69324107..2b9e84c3cd 100644
--- a/doc/articles/error_handling.html
+++ b/doc/articles/error_handling.html
@@ -1,4 +1,8 @@
 <!-- Error Handling and Go -->
+<!--
+  DO NOT EDIT: created by
+    tmpltohtml articles/error_handling.tmpl
+-->
 
 <p>
 If you have written any Go code you have probably encountered the built-in
diff --git a/doc/articles/error_handling.tmpl b/doc/articles/error_handling.tmpl
index 75800ae21a..508885a8fd 100644
--- a/doc/articles/error_handling.tmpl
+++ b/doc/articles/error_handling.tmpl
@@ -1,5 +1,5 @@
 <!-- Error Handling and Go -->
-
+{{donotedit}}
 <p>
 If you have written any Go code you have probably encountered the built-in
 <code>error</code> type. Go code uses <code>error</code> values to

コアとなるコードの解説

doc/articles/defer_panic_recover.tmpl および doc/articles/error_handling.tmpl

これらのファイルは、Go言語のドキュメント記事のテンプレートです。変更点として、ファイルの冒頭部分に{{donotedit}}という行が追加されています。

  • {{donotedit}}: これはGoのテンプレート構文の一部であり、tmpltohtmlツールが特別に処理するディレクティブです。このディレクティブが存在することで、tmpltohtmlは生成するHTMLファイルに「このファイルは自動生成されたものであり、手動で編集すべきではない」という警告コメントを挿入するようになります。

doc/articles/defer_panic_recover.html および doc/articles/error_handling.html

これらのファイルは、上記のテンプレートファイルからtmpltohtmlツールによって生成されるHTMLファイルです。変更点として、HTMLファイルの冒頭の既存のコメントの下に、新しいHTMLコメントブロックが追加されています。

<!--
  DO NOT EDIT: created by
    tmpltohtml articles/defer_panic_recover.tmpl
-->

（または error_handling.tmpl の場合）

  • <!-- DO NOT EDIT: created by ... -->: このコメントは、tmpltohtmlツールが{{donotedit}}ディレクティブを検出した結果として、生成されたHTMLファイルに自動的に挿入されたものです。このコメントは、このHTMLファイルが手動で編集されるべきではなく、tmpltohtmlツールによって特定のテンプレートファイルから生成されたものであることを明確に示しています。これにより、開発者が誤ってこのファイルを直接変更してしまうことを防ぎ、ドキュメントの一貫性とメンテナンス性を保つことができます。

この変更は、Goプロジェクトにおけるドキュメント生成のベストプラクティスを強化し、開発ワークフローをより堅牢にするためのものです。

関連リンク

参考にした情報源リンク

  • Go言語のコミット履歴 (GitHub): https://github.com/golang/go/commits/master
  • Go言語のコードレビューシステム (Gerrit): https://go.dev/cl/ (コミットメッセージに記載されている https://golang.org/cl/5502088 は、このGerritシステムへのリンクです。)
  • HTMLコメントに関するMDN Web Docs: https://developer.mozilla.org/ja/docs/Web/HTML/Comments
  • Go言語のテンプレートに関する記事やチュートリアル (一般的な情報源)
    • Go言語のテンプレートに関する公式ブログ記事やチュートリアルは多数存在しますが、特定の記事を直接参照したわけではありません。text/templateの基本的な動作と、それがドキュメント生成にどのように利用されるかという一般的な知識に基づいています。
  • tmpltohtmlツールに関する情報: このツールはGoプロジェクト内部で使用されるカスタムツールであるため、公開された詳細なドキュメントは少ない可能性があります。その機能は、コミットの変更内容から推測されるものです。