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

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

このコミットは、Go言語の公式ドキュメント構造に重要な変更を加え、特に参照パスの正規化とコマンドドキュメントの専用ページの追加を行っています。これにより、ドキュメントのナビゲーションと参照の一貫性が向上し、ユーザーがGoツールに関する情報をより簡単に見つけられるようになります。

コミット

commit a22b0f82a2fd8e16cf3fab8701a3cff91c93177f
Author: Andrew Gerrand <adg@golang.org>
Date:   Mon Mar 5 15:30:27 2012 +1100

    doc: add command docs page, canonicalize reference paths
    
    R=golang-dev, kyle, r
    CC=golang-dev
    https://golang.org/cl/5728055

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

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

元コミット内容

doc: add command docs page, canonicalize reference paths

R=golang-dev, kyle, r
CC=golang-dev
https://golang.org/cl/5728055

変更の背景

このコミットの主な背景には、Go言語のドキュメント体系の改善があります。当時のGoドキュメントは、相対パスでのリンクが多く、各ドキュメントページのURL構造が統一されていませんでした。これにより、ドキュメント間のリンク切れや、ユーザーが特定の参照ドキュメント(仕様、メモリモデル、GDBデバッグなど)にアクセスする際のURLの予測可能性の欠如といった問題が生じていた可能性があります。

また、Goコマンドに関するドキュメントが散在しているか、一元的に参照できるページが存在しなかったため、ユーザーが利用可能なGoツールとその概要を把握しにくい状況でした。これらの課題を解決し、ドキュメントのユーザビリティと保守性を向上させるために、参照パスの正規化とコマンドドキュメントの専用ページ追加が計画されました。

前提知識の解説

  • 正規化 (Canonicalization): ウェブ開発において、正規化とは、複数の異なるURLが同じコンテンツを指す場合に、そのコンテンツの「公式」または「優先」されるURLを一つに定めるプロセスを指します。これにより、検索エンジン最適化(SEO)の観点からも有利になり、ユーザーにとっても一貫したアクセスポイントが提供されます。このコミットでは、Goドキュメント内の参照リンクを、より予測可能で安定したパス(例: /ref/spec)に統一することで、この正規化を実現しています。
  • HTML <!--{ ... }--> コメント内のメタデータ: Goのドキュメントシステムでは、HTMLファイルの冒頭に特別なコメントブロック <!--{ ... }--> を使用して、ページのタイトル ("Title") や、このコミットで追加された正規化されたパス ("Path") などのメタデータを埋め込んでいます。これは、ドキュメント生成ツールがこれらの情報を読み取り、サイト全体のナビゲーションやURL構造を構築するために利用されます。
  • Goコマンド: Go言語には、コンパイル、テスト、フォーマット、ドキュメント生成など、開発を支援するための様々なコマンドラインツールが付属しています。例えば、goコマンド自体がビルドや実行の主要なツールであり、gofmtはコードのフォーマット、godocはドキュメントの生成に使用されます。これらのコマンドに関する包括的な情報を提供することは、Go開発者にとって非常に重要です。

技術的詳細

このコミットは、主に以下の2つの技術的アプローチによってドキュメントの改善を図っています。

  1. 参照パスの正規化:

    • 既存の主要な参照ドキュメント(Go言語仕様、Goメモリモデル、GDBデバッグガイドなど)のHTMLファイルに、<!--{ ... }--> コメントブロック内に "Path": "/ref/..." という形式のメタデータを追加しています。これにより、これらのドキュメントの「公式」なURLパスが明示的に定義されます。
    • ドキュメント内の既存の相対リンク(例: <a href="go_spec.html">)を、新しく定義された正規化された絶対パス(例: <a href="/ref/spec">)に一括して変更しています。これにより、リンクの一貫性が保たれ、将来的なファイル構造の変更にも強くなります。
    • doc/reference.html ファイルは、Goドキュメントの主要な参照ページであり、このコミットで多くの内部リンクが正規化されたパスに更新されています。また、このページ自体も /ref/ という正規化されたパスを持つように設定されています。
  2. コマンドドキュメント専用ページの追加:

    • doc/reference-cmd.html という新しいHTMLファイルが作成されました。このファイルは、Go言語に付属する主要なコマンド(go, cgo, cov, fix, godoc, gofmt, prof, vet, yacc)のリストと簡単な説明、そしてそれぞれの詳細ドキュメントへのリンクを提供します。
    • この新しいページも、"Path": "/ref/cmd" という正規化されたパスを持つように設定されており、doc/reference.html からもこのページへのリンクが追加されています。これにより、Goコマンドに関する情報へのアクセスが集中化され、ユーザーがGoツール群を俯瞰しやすくなります。

これらの変更は、Goドキュメントの構造をより堅牢でユーザーフレンドリーなものにするための基盤を築いています。特に、正規化されたパスの導入は、ドキュメントのURLが安定し、外部からのリンクや検索エンジンによるインデックス作成にも有利に働きます。

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

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

  • doc/debugging_with_gdb.html: GDBデバッグガイドのHTMLファイル。
  • doc/effective_go.html: Effective GoのHTMLファイル。
  • doc/effective_go.tmpl: Effective Goのテンプレートファイル。
  • doc/go_faq.html: Go FAQのHTMLファイル。
  • doc/go_mem.html: GoメモリモデルのHTMLファイル。
  • doc/go_spec.html: Go言語仕様のHTMLファイル。
  • doc/reference-cmd.html: 新規追加されたコマンドドキュメントのHTMLファイル。
  • doc/reference.html: 主要な参照ページであるHTMLファイル。

具体的な変更内容は以下の通りです。

新規ファイル: doc/reference-cmd.html

<!--{
	"Title": "Command Documentation",
	"Path":  "/ref/cmd"
}-->

<p>
Click on the links for more documentation and usage messages.
</p>

<table class="dir">
<tr>
<th>Name</th>
<th>&nbsp;&nbsp;&nbsp;&nbsp;</th>
<th>Synopsis</th>
</tr>

<tr>
<td><a href="/cmd/go/">go</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>
Go is a tool for managing Go source code.
<br>
Besides compiling and running Go programs, the go command is also used to
invoke the other commands listed below. See the command docs for usage
details.
<br><br>
</td>
</tr>

<tr>
<td><a href="/cmd/cgo/">cgo</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Cgo enables the creation of Go packages that call C code.</td>
</tr>

<tr>
<td><a href="/cmd/cov/">cov</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Cov is a rudimentary code coverage tool.</td>
</tr>

<tr>
<td><a href="/cmd/fix/">fix</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Fix finds Go programs that use old features of the language and libraries
and rewrites them to use newer ones.</td>
</tr>

<tr>
<td><a href="/cmd/godoc/">godoc</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Godoc extracts and generates documentation for Go programs.</td>
</tr>

<tr>
<td><a href="/cmd/gofmt/">gofmt</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Gofmt formats Go programs.</td>
</tr>

<tr>
<td><a href="/cmd/prof/">prof</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Prof is a rudimentary real-time profiler.</td>
</tr>

<tr>
<td><a href="/cmd/vet/">vet</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Vet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string.</td>
</tr>

<tr>
<td><a href="/cmd/yacc/">yacc</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Yacc is a version of yacc for Go.</td>
</tr>

</table>

<p>
This is an abridged list. See the <a href="/cmd/">full command reference</a>
for documentation of the compilers and more.
</p>

doc/reference.html の変更点(抜粋)

--- a/doc/reference.html
+++ b/doc/reference.html
@@ -1,24 +1,25 @@
 <!--{
-"Title": "References"
+"Title": "References",
+"Path":  "/ref/"
 }-->

 <img src="/doc/gopher/ref.png" align="right"/>

-<p>Good bathroom reading.</p>
+<p>Good bedtime reading.</p>

 <div>

 <h3 id="pkg"><a href="/pkg/">Package Documentation</a></h3>
 <p>
-The built-in documentation for the Go standard library.
+The documentation for the Go standard library.
 </p>

-<h3 id="cmd"><a href="/cmd/">Command Documentation</a></h3>
+<h3 id="cmd"><a href="/ref/cmd">Command Documentation</a></h3>
 <p>
-The built-in documentation for the Go tools.
+The documentation for the Go tools.
 </p>

-<h3 id="spec"><a href="go_spec.html">Language Specification</a></h3>
+<h3 id="spec"><a href="/ref/spec">Language Specification</a></h3>
 <p>
 The official Go Language specification. 
 </p>
@@ -29,19 +30,30 @@ The documentation for
 <a href="http://code.google.com/appengine/">Google App Engine</a>'s Go runtime.
 </p>

-<h3 id="release"><a href="devel/release.html">Release History</a></h3>
-<p>A summary of the changes between Go releases.</p>
-
-<h3 id="go_mem"><a href="go_mem.html">The Go Memory Model</a></h3>
+<h3 id="go_mem"><a href="/ref/mem">The Go Memory Model</a></h3>
 <p>
 A document that specifies the conditions under which reads of a variable in
 one goroutine can be guaranteed to observe values produced by writes to the
 same variable in a different goroutine.
 </p>

-<h3 id="debugging_with_gdb"><a href="debugging_with_gdb.html">Debugging Go Code with GDB</a></h3>
+<h3 id="debugging_with_gdb"><a href="/ref/gdb">Debugging Go Code with GDB</a></h3>
 <p>
 Using GDB to debug Go programs.
 </p>

+<h3 id="articles">Articles</h2>
+
+<ul>
+<li><a href="http://blog.golang.org/2011/03/c-go-cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
+<li><a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a></li>
+<li><a href="/doc/articles/slices_usage_and_internals.html">Go Slices: usage and internals</a></li>
+<li><a href="http://blog.golang.org/2011/03/godoc-documenting-go-code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
+<li><a href="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
+</ul>
+
+<p>
+See the <a href=/doc/#articles">documentation page</a> for more articles.
+</p>
+
 </div>

他のHTMLファイル (debugging_with_gdb.html, effective_go.html, effective_go.tmpl, go_faq.html, go_mem.html, go_spec.html) も同様に、<!--{ ... }--> コメント内に "Path" メタデータが追加され、内部の相対リンクが正規化された絶対パスに更新されています。

コアとなるコードの解説

このコミットの「コード」は、Go言語のソースコードではなく、GoドキュメントのHTMLファイル群です。これらのHTMLファイルは、Goのドキュメント生成システムによって処理され、最終的なウェブサイトとして公開されます。

  • doc/reference-cmd.html の追加:

    • このファイルは、Goコマンドの包括的なリストと簡単な説明を提供します。各コマンド名(例: go, cgo, gofmt)は、それぞれの詳細なドキュメントページへのリンクになっています。これにより、ユーザーはGoツール群の全体像を把握し、特定のツールの詳細に素早くアクセスできるようになります。
    • "Path": "/ref/cmd" というメタデータは、このページが /ref/cmd というURLでアクセスされるべきであることをドキュメントシステムに伝えます。
  • 既存HTMLファイルの "Path" メタデータ追加とリンクの正規化:

    • doc/debugging_with_gdb.html"Path": "/ref/gdb" が追加されたように、各主要ドキュメントファイルにそのページの正規化されたURLパスが定義されました。これは、ドキュメントシステムがこれらのパスを認識し、サイトマップの生成や内部リンクの解決に利用するためのものです。
    • 例えば、doc/effective_go.html 内の <a href="go_spec.html"><a href="/ref/spec"> に変更されたように、すべての関連する内部リンクが相対パスから正規化された絶対パスに更新されました。これにより、ドキュメントの内部構造がより堅牢になり、将来的にファイルが移動してもリンクが壊れる可能性が低減されます。
    • doc/reference.html は、Goドキュメントの主要な参照ハブとして機能します。このコミットでは、既存の参照セクション(パッケージドキュメント、言語仕様、メモリモデルなど)へのリンクがすべて正規化されたパスに更新されました。
    • また、doc/reference.html には「Articles」セクションが新設され、Goブログの重要な記事へのリンクが追加されました。これにより、ユーザーはGoに関するより深い洞察や特定のトピックに関する解説記事にアクセスしやすくなります。

これらの変更は、Goドキュメントのナビゲーション体験を大幅に改善し、情報の発見性を高めることを目的としています。

関連リンク

参考にした情報源リンク

  • コミットハッシュ: a22b0f82a2fd8e16cf3fab8701a3cff91c93177f
  • GitHubコミットページ: https://github.com/golang/go/commit/a22b0f82a2fd8e16cf3fab8701a3cff91c93177f
  • Gerrit Change-Id: 5728055 (コミットメッセージに記載されているGoのコードレビューシステムへのリンク)
  • Go言語のドキュメント構造に関する一般的な知識
  • HTMLの基本的な構造とリンクの仕組み
  • ウェブサイトの正規化に関する一般的な概念