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

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

このコミットは、Go言語の公式ドキュメントにおけるフラグメントリンクの修正に関するものです。具体的には、ドキュメント内のHTMLファイルに存在する内部リンクが、正しいアンカー（#hdr-プレフィックスを持つID）を参照するように更新されています。これにより、リンクをクリックした際に意図したセクションへ正確にジャンプできるようになります。

コミット

commit 399a36a634d58f14f1945b83a84b884c9dfb72da
Author: Andrew Gerrand <adg@golang.org>
Date:   Tue Jan 15 19:25:16 2013 +1100

    doc: fix various fragment links
    
    R=dsymonds
    CC=golang-dev
    https://golang.org/cl/7094058

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

https://github.com/golang/go/commit/399a36a634d58f14f1945b83a84b884c9dfb72da

元コミット内容

doc: fix various fragment links

R=dsymonds
CC=golang-dev
https://golang.org/cl/7094058

変更の背景

Go言語の公式ドキュメントは、多くのHTMLファイルで構成されており、それぞれのファイル内で特定のセクションへの内部リンク（フラグメントリンク）が多用されています。これらのリンクは、<a>タグのhref属性に#に続くIDを指定することで機能します。しかし、ドキュメントの生成プロセスやHTMLの構造変更により、一部のフラグメントリンクが正しく機能しなくなっていた可能性があります。具体的には、GoドキュメントのセクションIDには慣習的にhdr-というプレフィックスが付与されることが多く、このプレフィックスが欠落しているためにリンクが壊れていたと考えられます。

このコミットは、ユーザーがドキュメントを閲覧する際に、リンクをクリックしても目的のセクションに移動できないという問題を解決するために行われました。ドキュメントの正確性とユーザビリティを向上させることが目的です。

前提知識の解説

HTMLにおけるフラグメントリンク

HTMLにおいて、フラグメントリンク（またはアンカーリンク）は、同じHTMLドキュメント内の特定のセクションへ直接ジャンプするためのハイパーリンクです。これは、<a>タグのhref属性に#記号とそれに続くターゲットとなる要素のid属性の値を指定することで作成されます。

例:

<a href="#section-id">セクションへジャンプ</a>
...
<h2 id="section-id">対象セクション</h2>

この例では、「セクションへジャンプ」というリンクをクリックすると、id="section-id"を持つ<h2>要素の位置までページがスクロールします。

Goドキュメントの構造とhdr-プレフィックス

Go言語の公式ドキュメントは、godocツールやその他のドキュメント生成システムによって生成されています。これらのシステムは、MarkdownやGoのソースコードコメントからHTMLドキュメントを生成する際に、見出し（<h1>, <h2>など）に対して自動的に一意のIDを割り当てることが一般的です。Goのドキュメントでは、これらの自動生成されるIDにhdr-というプレフィックスが付与される慣習があります。例えば、go buildコマンドに関するセクションの見出しが「Compile packages and dependencies」であれば、そのIDはhdr-Compile_packages_and_dependenciesのようになることがあります。

このhdr-プレフィックスは、IDの衝突を避けるためや、自動生成されたIDであることを示すために使用されます。したがって、ドキュメント内でこれらのセクションへのリンクを作成する際には、このプレフィックスを含める必要があります。

技術的詳細

このコミットの技術的詳細は、HTMLドキュメント内の<a>タグのhref属性の修正に集約されます。変更は、既存のフラグメントリンクのhref属性値にhdr-プレフィックスを追加するという単純なものです。

具体的には、以下のパターンで修正が行われています。

変更前: /cmd/go/#Compile_packages_and_dependencies 変更後: /cmd/go/#hdr-Compile_packages_and_dependencies

この修正は、Goドキュメントの生成システムが、特定の見出しに対してhdr-プレフィックスを持つIDを割り当てているという事実に基づいています。リンクがこの新しいID形式に一致するように更新することで、ブラウザは正しくターゲットのセクションを見つけ、ページをスクロールできるようになります。

影響を受けるファイルは、Goドキュメントの様々な記事やコード例のHTMLファイルです。これらは主にdoc/articles/ディレクトリとdoc/ディレクトリ直下に存在します。

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

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

  • doc/articles/c_go_cgo.html
  • doc/articles/go_command.html
  • doc/articles/laws_of_reflection.html
  • doc/code.html
  • doc/go_faq.html

それぞれのファイルで、<a>タグのhref属性内のフラグメント識別子（#以降の部分）にhdr-が追加されています。

例: doc/articles/c_go_cgo.html の変更点

--- a/doc/articles/c_go_cgo.html
+++ b/doc/articles/c_go_cgo.html
@@ -149,9 +149,9 @@ is more complex than a single function call), as in this rewrite of
 </p>
 
 <p>
-To build cgo packages, just use <a href="/cmd/go/#Compile_packages_and_dependencies">"
+To build cgo packages, just use <a href="/cmd/go/#hdr-Compile_packages_and_dependencies">"
  <code>go build</code>"</a> or
-<a href="/cmd/go/#Compile_and_install_packages_and_dependencies">"<code>go install</code>
+<a href="/cmd/go/#hdr-Compile_and_install_packages_and_dependencies">"<code>go install</code>
 "</a> as usual. The go tool recognizes the special <code>"C"</code> import and automatically
 uses cgo for those files.
 </p>

コアとなるコードの解説

変更されたコードは、HTMLのハイパーリンクのhref属性です。これは、ウェブブラウザがリンクをクリックしたときにどこに移動するかを決定する基本的な要素です。

例えば、doc/articles/c_go_cgo.html の以下の行を見てみましょう。

変更前: <a href="/cmd/go/#Compile_packages_and_dependencies">

変更後: <a href="/cmd/go/#hdr-Compile_packages_and_dependencies">

この変更は、リンクのターゲットが、Compile_packages_and_dependenciesというIDを持つ要素ではなく、hdr-Compile_packages_and_dependenciesというIDを持つ要素であることを明示しています。これにより、ドキュメント生成システムが自動的に生成するIDとリンクが一致し、リンク切れが解消されます。

同様の修正が、他の4つのファイルでも行われています。これらはすべて、GoコマンドのサブコマンドやGoの標準パッケージのドキュメントへの内部リンクです。

  • doc/articles/go_command.html: go getコマンドへのリンク
  • doc/articles/laws_of_reflection.html: reflect.TypeOf関数へのリンク
  • doc/code.html: go help testおよびgo help remoteコマンドへのリンク
  • doc/go_faq.html: go vetおよびgo testコマンドへのリンク

これらの修正は、Goドキュメントの整合性とナビゲーションの正確性を保証するために不可欠です。

関連リンク

参考にした情報源リンク