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

このコミットは、Go言語の公式ドキュメント内のリンクを絶対パスから相対パスに修正するものです。具体的には、以下のHTMLドキュメントが変更されています。

doc/effective_go.html
doc/go1.3.html
doc/go_faq.html
doc/go_spec.html

コミット

doc: replace absolute links to golang.org with relative links
Currently tip.golang.org leads to golang.org and
local godoc also leads to golang.org (when you don't have internet connectivity).

LGTM=crawshaw
R=golang-codereviews, crawshaw
CC=golang-codereviews
https://golang.org/cl/100200043

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

https://github.com/golang/go/commit/2e1ddeb136d3a74390f4e8ea28c6605cc6ab48b1

元コミット内容

doc: replace absolute links to golang.org with relative links
Currently tip.golang.org leads to golang.org and
local godoc also leads to golang.org (when you don't have internet connectivity).

LGTM=crawshaw
R=golang-codereviews, crawshaw
CC=golang-codereviews
https://golang.org/cl/100200043

変更の背景

このコミットの主な目的は、Go言語のドキュメント内で使用されているgolang.orgへの絶対リンクを相対リンクに置き換えることです。この変更は、ドキュメントが異なる環境で閲覧される際に、リンクの挙動をより適切にするために行われました。

具体的には、以下の2つのシナリオが考慮されています。

tip.golang.orgでの閲覧: tip.golang.orgは、Go言語の開発版（tip）のドキュメントやウェブサイトをホストしている場合があります。もしドキュメント内のリンクがhttp://golang.org/のような絶対パスで記述されていると、tip.golang.org上でドキュメントを閲覧しているユーザーがリンクをクリックした際に、意図せず本番環境のgolang.orgにリダイレクトされてしまう可能性があります。相対リンクを使用することで、tip.golang.orgのサブパスとしてリンクが解決され、開発版のドキュメント内で完結したナビゲーションが可能になります。
ローカルのgodocでの閲覧（オフライン環境）: godocは、Go言語のソースコードからドキュメントを生成し、ローカルでウェブサーバーとして提供するツールです。開発者やユーザーは、インターネット接続がない環境でもgodocを使ってGoのドキュメントを閲覧できます。しかし、ドキュメント内のリンクがhttp://golang.org/のような絶対パスである場合、オフライン環境でそのリンクをクリックすると、外部のgolang.orgへのアクセスを試みてしまい、リンク切れやエラーが発生します。相対リンクにすることで、godocが提供するローカルのパスに対してリンクが解決され、オフラインでもドキュメント内のナビゲーションがスムーズに行えるようになります。

これらの問題を解決し、ドキュメントの利便性と堅牢性を向上させるために、絶対リンクから相対リンクへの変更が実施されました。

前提知識の解説

1. 絶対パスと相対パス (URL/URI)

ウェブ開発において、リソース（HTMLファイル、画像、CSS、JavaScriptなど）へのパスを指定する方法には、大きく分けて「絶対パス」と「相対パス」の2種類があります。

絶対パス (Absolute Path):
- リソースの完全な場所を、プロトコル（http://やhttps://など）、ドメイン名、ポート番号、パス、ファイル名などを含めて指定します。
- 例: http://golang.org/pkg/fmt/
- この形式は、リソースがどこにあるかに関わらず、常に同じ場所を指します。しかし、ドキュメントが異なるドメインやサブドメインでホストされる場合、意図しない外部サイトへの遷移を引き起こす可能性があります。また、オフライン環境では外部リソースにアクセスできないため、リンクが機能しなくなります。
相対パス (Relative Path):
- 現在閲覧しているドキュメントの場所を基準として、リソースの場所を指定します。プロトコルやドメイン名は含まれません。
- 例: /pkg/fmt/ (ルート相対パス) または ../images/logo.png (ディレクトリ相対パス)
- このコミットで変更されているのは、ルート相対パスです。これは、現在のドメインのルートディレクトリからのパスを示します。例えば、http://example.com/docs/index.htmlで/pkg/fmt/というリンクをクリックすると、http://example.com/pkg/fmt/に遷移します。
- 相対パスは、ドキュメントが異なる環境（開発サーバー、ステージングサーバー、本番サーバー、ローカルファイルシステムなど）でホストされる場合でも、リンクがその環境のベースURLに基づいて適切に解決されるため、柔軟性が高いという利点があります。

2. `golang.org`

golang.orgは、Go言語の公式ウェブサイトです。Go言語に関する最新情報、ダウンロード、ドキュメント、ブログ、コミュニティリソースなどが提供されています。Go言語の学習や開発において中心的な役割を果たすサイトです。

3. `tip.golang.org`

tip.golang.orgは、Go言語の「tip」（開発版）のドキュメントやウェブサイトをホストするために使用されることが多いサブドメインです。Go言語の次期リリースに向けた最新の変更や機能が反映されたドキュメントを、本番環境のgolang.orgとは別に提供することで、開発者やテスターが先行して内容を確認できるようにしています。

4. `godoc`

godocは、Go言語のツールチェーンに含まれるコマンドラインツールです。Goのソースコード（.goファイル）からコメントや関数シグネチャなどを解析し、自動的にドキュメントを生成します。生成されたドキュメントは、ウェブブラウザを通じて閲覧できる形式でローカルに提供されます。

godocの主な特徴は以下の通りです。

コードからのドキュメント生成: Goのコード規約に従って記述されたコメント（特にパッケージ、関数、型、変数などに対するコメント）を読み取り、整形されたドキュメントを生成します。
ローカルサーバー機能: godoc -http=:6060のように実行することで、指定したポートでウェブサーバーを起動し、ローカルマシンからブラウザでドキュメントにアクセスできるようになります。
オフライン利用: ローカルにGoのソースコードがあれば、インターネット接続がなくてもドキュメントを閲覧できます。これは、開発者がオフライン環境で作業する際に非常に便利です。

このコミットの背景にある問題は、まさにこのgodocのオフライン利用時に、ドキュメント内の絶対リンクが外部のgolang.orgへのアクセスを試みてしまう点にありました。

技術的詳細

このコミットで行われた技術的な変更は、HTMLの<a>タグのhref属性の値を、絶対URLからルート相対URLに変更することです。

変更前:

<a href="http://golang.org/pkg/fmt/"><code>fmt</code> package</a>

変更後:

<a href="/pkg/fmt/"><code>fmt</code> package</a>

この変更がもたらす技術的な影響は以下の通りです。

URL解決のメカニズム:
- 絶対URL (http://golang.org/pkg/fmt/): ブラウザは、このURLをそのまま解釈し、指定されたプロトコル (http) とホスト名 (golang.org) を使用してリソースにアクセスしようとします。これは、ドキュメントがどこでホストされていても、常にgolang.orgのfmtパッケージのドキュメントを指します。
- ルート相対URL (/pkg/fmt/): ブラウザは、現在閲覧しているページのドメインとプロトコルをベースとして、指定されたパスを解決します。
  - 例1: https://golang.org/doc/effective_go.html で /pkg/fmt/ をクリックすると、https://golang.org/pkg/fmt/ に遷移します。
  - 例2: https://tip.golang.org/doc/effective_go.html で /pkg/fmt/ をクリックすると、https://tip.golang.org/pkg/fmt/ に遷移します。
  - 例3: http://localhost:6060/doc/effective_go.html (ローカルのgodocサーバー) で /pkg/fmt/ をクリックすると、http://localhost:6060/pkg/fmt/ に遷移します。
オフライン対応の強化:
- godocがローカルでドキュメントを提供している場合、絶対URLは外部のgolang.orgへのネットワーク接続を必要とします。インターネット接続がない場合、これらのリンクは機能しません。
- 相対URLに変更することで、godocが提供するローカルのベースURL（例: http://localhost:6060）に対してリンクが解決されるため、すべてのリンクがローカルで完結し、オフライン環境でもドキュメント内のナビゲーションが完全に機能するようになります。
開発・ステージング環境での一貫性:
- tip.golang.orgのような開発・ステージング環境では、本番環境とは異なるバージョンのドキュメントや機能が提供されています。絶対URLが使用されていると、これらの環境でドキュメントを閲覧しているユーザーが、リンクをクリックすることで本番環境の古いドキュメントにリダイレクトされてしまう可能性があります。
- 相対URLにすることで、tip.golang.org上で閲覧しているドキュメント内のリンクは、tip.golang.orgのパスとして解決され、常にその環境の最新のドキュメントを参照するようになります。これにより、開発・ステージング環境でのテストや確認がより正確に行えるようになります。

この変更は、Goドキュメントの配布と利用の柔軟性を高め、特にオフライン環境や開発環境でのユーザーエクスペリエンスを大幅に改善するものです。

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

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

`doc/effective_go.html`

--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -214,7 +214,7 @@ not be used.\n One adjustment <code>godoc</code> does do is to display indented\n text in a fixed-width font, suitable for program snippets.\n The package comment for the\n-<a href="http://golang.org/pkg/fmt/"><code>fmt</code> package</a> uses this to good effect.\n+<a href="/pkg/fmt/"><code>fmt</code> package</a> uses this to good effect.\n </p>\n \n <p>\n@@ -710,7 +710,7 @@ Erroneous encodings consume one byte and produce the\n replacement rune U+FFFD.\n (The name (with associated builtin type) <code>rune</code> is Go terminology for a\n single Unicode code point.\n-See <a href="http://golang.org/ref/spec#Rune_literals">the language specification</a>\n+See <a href="/ref/spec#Rune_literals">the language specification</a>\n for details.)\n The loop\n </p>\n```

### `doc/go1.3.html`
```diff
--- a/doc/go1.3.html
+++ b/doc/go1.3.html
@@ -233,7 +233,7 @@ The cumulative effect can be a 50-70% reduction in collector pause time.\n </li>\n \n <li>\n-The race detector (see <a href="http://golang.org/doc/articles/race_detector.html">this guide</a>)\n+The race detector (see <a href="/doc/articles/race_detector.html">this guide</a>)\n is now about 40% faster.\n </li>\n \n```

### `doc/go_faq.html`
```diff
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -940,9 +940,9 @@ How are libraries documented?</h3>\n There is a program, <code>godoc</code>, written in Go, that extracts\n package documentation from the source code. It can be used on the\n command line or on the web. An instance is running at\n-<a href="http://golang.org/pkg/">http://golang.org/pkg/</a>.\n+<a href="/pkg/">http://golang.org/pkg/</a>.\n In fact, <code>godoc</code> implements the full site at\n-<a href="http://golang.org/">http://golang.org/</a>.\n+<a href="/">http://golang.org/</a>.\n </p>\n \n <h3 id="Is_there_a_Go_programming_style_guide">\n@@ -1437,7 +1437,7 @@ each closure shares that single variable. When the closure runs, it prints the\n value of <code>v</code> at the time <code>fmt.Println</code> is executed,\n but <code>v</code> may have been modified since the goroutine was launched.\n To help detect this and other problems before they happen, run\n-<a href="http://golang.org/cmd/go/#hdr-Run_go_tool_vet_on_packages"><code>go vet</code></a>.\n+<a href="/cmd/go/#hdr-Run_go_tool_vet_on_packages"><code>go vet</code></a>.\n </p>\n \n <p>\n```

### `doc/go_spec.html`
```diff
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -23,7 +23,7 @@ TODO\n \n <p>\n This is a reference manual for the Go programming language. For\n-more information and other documents, see <a href="http://golang.org/">http://golang.org</a>.\n+more information and other documents, see <a href="/">http://golang.org</a>.\n </p>\n \n <p>\n```

## コアとなるコードの解説

上記の変更箇所を見ると、すべての変更がHTMLの`<a>`タグの`href`属性に対するものであることがわかります。具体的には、`href`属性の値が`http://golang.org/`で始まる絶対URLから、`/`で始まるルート相対URLに置き換えられています。

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

変更前:
```html
<a href="http://golang.org/pkg/fmt/"><code>fmt</code> package</a>

このリンクは、fmtパッケージのドキュメントを指しています。http://golang.org/pkg/fmt/という絶対URLが指定されているため、このリンクをクリックすると常にgolang.orgのサイトにアクセスしようとします。