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

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

このコミットは、Go言語の公式ドキュメンテーションの一部であるdoc/go1.htmlおよびdoc/go1.tmplファイル内の内部リンクのURLを修正することを目的としています。具体的には、Go標準ライブラリのパッケージ（go/parser、go/doc、go/ast、go/tokenなど）への相対リンクを、/pkg/プレフィックスを含む絶対パス形式に更新しています。これにより、ドキュメンテーションがウェブサイト上で正しく表示され、リンク切れを防ぐことが保証されます。

コミット

  • コミットハッシュ: 75e9d24213992ea2077283383cb8705fefc2973a
  • 作者: Gustavo Niemeyer gustavo@niemeyer.net
  • コミット日時: 2012年1月25日(水) 23:42:36 -0200

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

https://github.com/golang/go/commit/75e9d24213992ea2077283383cb8705fefc2973a

元コミット内容

doc/go1: fix urls

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

変更の背景

この変更は、Go言語のバージョン1（Go 1）のリリースに向けたドキュメンテーションの整備の一環として行われました。Go言語の公式ウェブサイトやドキュメンテーションシステムでは、パッケージのドキュメンテーションは通常/pkg/というパスプレフィックスの下に配置されます。例えば、go/parserパッケージのドキュメンテーションはhttps://golang.org/pkg/go/parser/のようなURLでアクセスされます。

コミット前のdoc/go1.htmlおよびdoc/go1.tmplファイルでは、これらのパッケージへのリンクがgo/parser/#ParseFileのように/pkg/を含まない相対パスで記述されていました。これは、特定の環境やウェブサーバーの設定によっては正しく解決されず、リンク切れや意図しないページへのリダイレクトを引き起こす可能性がありました。

このコミットは、これらのURLを/pkg/go/parser/#ParseFileのように絶対パス形式に修正することで、ドキュメンテーションの堅牢性を高め、Go 1リリース時のユーザー体験を向上させることを目的としています。これにより、ドキュメンテーションがどのディレクトリから提供されても、常に正しいパッケージドキュメンテーションページを指すようになります。

前提知識の解説

Go言語のパッケージとドキュメンテーション

Go言語は、コードをパッケージという単位で整理します。標準ライブラリには、fmt、net/http、go/parserなど、多くのパッケージが含まれています。Goのツールチェインには、これらのパッケージのドキュメンテーションを生成・表示するためのgodocツールが組み込まれています。公式のドキュメンテーションサイト（当時はgolang.org、現在はpkg.go.dev）は、このgodocツールによって生成された情報をウェブ上で公開しています。

HTMLのハイパーリンクとURLの解決

HTMLの<a>タグのhref属性は、リンク先のURLを指定します。URLには大きく分けて以下の2種類があります。

  1. 相対URL: 現在のドキュメントの場所を基準にしてリンク先を指定します。例えば、/docs/index.htmlというページから../images/logo.pngと指定すると、images/logo.pngは/images/logo.pngとして解決されます。go/parser/#ParseFileのような形式は、現在のディレクトリからの相対パスとして解釈されます。
  2. 絶対URL: プロトコル（http://やhttps://）から始まる完全なURL、またはウェブサイトのルート（/）から始まるパスを指定します。例えば、/pkg/go/parser/#ParseFileは、ウェブサイトのルートディレクトリ直下のpkg/go/parser/というパスを指します。

ウェブサーバーは、相対URLを現在のページのURLを基準に解決します。もしドキュメンテーションファイルがウェブサーバーのルート直下ではなく、例えば/docs/というサブディレクトリに配置されていた場合、go/parser/#ParseFileという相対URLは/docs/go/parser/#ParseFileと解決されてしまい、意図したパッケージドキュメンテーション（/pkg/go/parser/）とは異なる場所を指すことになります。

Go 1リリース

Go 1は、Go言語の最初の安定版リリースであり、言語仕様と標準ライブラリの互換性が保証される重要なマイルストーンでした。このリリースに向けて、ドキュメンテーションの正確性と堅牢性は非常に重視されました。

技術的詳細

このコミットは、doc/go1.htmlとdoc/go1.tmplという2つのファイルを変更しています。これらのファイルは、Go 1のリリースノートや変更点をまとめたドキュメンテーションの一部です。

変更内容は、HTMLの<a>タグのhref属性内のURLパターンを修正することに集約されます。具体的には、以下のGo標準ライブラリパッケージへのリンクが対象となりました。

  • go/parserパッケージのParseFile、ParseDir、ParseExpr関数
  • go/docパッケージ
  • go/docパッケージのAllDecls定数
  • go/astパッケージのast.CommentGroup型のTextメソッド
  • go/tokenパッケージのtoken.FileSet型とIterateメソッド

これらのリンクは、元々href="go/parser/#ParseFile"のように記述されていましたが、コミットによってhref="/pkg/go/parser/#ParseFile"のように、パスの先頭に/pkg/が追加されました。

この修正の技術的な意味合いは以下の通りです。

  1. 絶対パスへの変換: 相対パスからウェブサイトのルートを基準とした絶対パスへの変換です。これにより、ドキュメンテーションファイルがウェブサーバー上のどこに配置されても、リンクが常にhttps://golang.org/pkg/...のような正しいURLに解決されるようになります。
  2. GoドキュメンテーションのURL構造への準拠: Goの公式ドキュメンテーションサイトでは、パッケージのドキュメンテーションは/pkg/パスの下に集約されています。この修正は、その標準的なURL構造に明示的に準拠させるものです。
  3. 堅牢性の向上: リンク切れのリスクを低減し、ドキュメンテーションの信頼性を高めます。特に、Go 1という重要なリリースにおいて、ユーザーが正確な情報にアクセスできることは極めて重要です。

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

以下は、doc/go1.htmlファイルにおける変更の抜粋です。doc/go1.tmplも同様の変更が適用されています。

--- a/doc/go1.html
+++ b/doc/go1.html
@@ -936,13 +936,13 @@ for that purpose.
 <p>
 The set of parse functions provided by the <a href="/pkg/go/parser/"><code>go/parser</code></a>
 package has been reduced to the primary parse function
-<a href="go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
-convenience functions <a href="go/parser/#ParseDir"><code>ParseDir</code></a>
-and <a href="go/parser/#ParseExpr"><code>ParseExpr</code></a>.
+<a href="/pkg/go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
+convenience functions <a href="/pkg/go/parser/#ParseDir"><code>ParseDir</code></a>
+and <a href="/pkg/go/parser/#ParseExpr"><code>ParseExpr</code></a>.
 </p>
 
 <p>
-The type names of the <a href="go/doc/"><code>go/doc</code></a> package have been
+The type names of the <a href="/pkg/go/doc/"><code>go/doc</code></a> package have been
 streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code>
 is now <code>Package</code>, <code>ValueDoc</code> is <code>Value</code>, etc.
 Also, all types now consistently have a <code>Name</code> field (or <code>Names</code>,
@@ -958,19 +958,19 @@ documentation for a package is created with:
 
 <p>
 where the new <code>mode</code> parameter specifies the operation mode:
-if set to <a href="go/doc/#AllDecls"><code>AllDecls</code></a>, all declarations
+if set to <a href="/pkg/go/doc/#AllDecls"><code>AllDecls</code></a>, all declarations
 (not just exported ones) are considered.
 The function <code>NewFileDoc</code> was removed, and the function
 <code>CommentText</code> has become the method
-<a href="go/ast/#Text"><code>Text</code></a> of
-<a href="go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.
+<a href="/pkg/go/ast/#Text"><code>Text</code></a> of
+<a href="/pkg/go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.
 </p>
 
 <p>
-In package <a href="go/token/"><code>go/token</code></a>, the
-<a href="go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code>
+In package <a href="/pkg/go/token/"><code>go/token</code></a>, the
+<a href="/pkg/go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code>
 (which originally returned a channel of <code>*token.File</code>s) has been replaced
-with the iterator <a href="go/token/#FileSet.Iterate"><code>Iterate</code></a> that
+with the iterator <a href="/pkg/go/token/#FileSet.Iterate"><code>Iterate</code></a> that
 accepts a function argument instead.
 </p>

コアとなるコードの解説

上記の差分は、doc/go1.htmlファイル内の複数の<a>タグのhref属性が変更されていることを示しています。

例えば、最初の変更点では、go/parserパッケージのParseFile関数へのリンクが以下のように修正されています。

  • 変更前: <a href="go/parser/#ParseFile">
  • 変更後: <a href="/pkg/go/parser/#ParseFile">

この修正は、href属性の値の先頭に/pkg/という文字列を追加するものです。

  • go/parser/#ParseFile: これは相対パスです。このHTMLファイルが置かれているディレクトリを基準にして、go/parser/というサブディレクトリ内の#ParseFileというアンカー（HTML要素のID）を指します。もしこのHTMLファイルがウェブサーバーのルート直下になければ、リンクは正しく解決されません。
  • /pkg/go/parser/#ParseFile: これは絶対パスです。ウェブサーバーのルートディレクトリ（/）を基準にして、pkg/go/parser/というパス内の#ParseFileというアンカーを指します。これにより、このHTMLファイルがウェブサーバー上のどこに配置されても、常にhttps://golang.org/pkg/go/parser/#ParseFileのような正しいURLに解決されることが保証されます。

同様の修正が、go/doc、go/ast、go/tokenパッケージへのリンクにも適用されています。これらの変更は、Go言語の公式ドキュメンテーションサイトのURL構造に合わせたものであり、ドキュメンテーションのリンクの堅牢性と正確性を確保するために不可欠でした。

関連リンク

  • Gerrit Change-ID: https://golang.org/cl/5577051 (Goプロジェクトが使用しているコードレビューシステムであるGerritの変更セットへのリンク)

参考にした情報源リンク

  • Go言語公式ドキュメンテーション (当時のgolang.orgの構造を想定)
  • HTMLの<a>タグとhref属性に関する一般的な知識
  • 相対URLと絶対URLの概念