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

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

このコミットは、Go言語プロジェクトのドキュメントファイル doc/contribute.html に対する修正です。具体的には、HTMLタグの修正と余分なスペースの削除が行われています。これは、ドキュメントの可読性と正確性を向上させるための軽微な修正です。

コミット

  • コミットハッシュ: aecbcd0914bb99553862071ffeb0b355b8907f34
  • Author: Oling Cat olingcat@gmail.com
  • Date: Fri Feb 15 14:01:12 2013 +1100

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

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

元コミット内容

doc/contribute: fix some tags, remove extra space.

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

変更の背景

このコミットの背景は、Go言語プロジェクトへの貢献方法を説明するドキュメント doc/contribute.html の品質向上にあります。ドキュメント内のHTMLタグの誤りや余分なスペースは、レンダリングされたページの表示崩れや読みにくさにつながる可能性があります。この修正は、ユーザーがドキュメントをより正確に、そして快適に読めるようにするための、保守的な改善活動の一環です。特に、コードスニペットやコマンドを表現する <code> タグの正確な使用は、技術ドキュメントにおいて非常に重要です。

前提知識の解説

HTML (HyperText Markup Language)

HTMLは、ウェブページの構造を定義するためのマークアップ言語です。タグ（例: <p>, <code>）を使用して、テキスト、画像、リンクなどの要素を構造化します。

  • <p> タグ: 段落（paragraph）を定義します。通常、ブロックレベル要素であり、前後に改行が入ります。
  • <code> タグ: インライン要素であり、コンピュータのコードの一部であることを示します。通常、等幅フォントで表示され、コードスニペットやコマンドを表現する際に使用されます。

Mercurial (Hg)

Mercurialは、分散型バージョン管理システム（DVCS）の一つです。Gitと同様に、コードの変更履歴を管理し、複数の開発者間での共同作業を容易にします。Go言語プロジェクトは、かつてMercurialを主要なバージョン管理システムとして使用していました（現在はGitに移行しています）。

  • hg help codereview: Mercurialのコードレビュー拡張機能に関するヘルプを表示するコマンド。
  • $GOROOT: Go言語のインストールディレクトリを示す環境変数。Goのソースコードやツールが配置されています。
  • hg sync: リモートリポジトリとローカルリポジトリの同期を取るコマンド。
  • hg change -D <CL_ID>: 指定された変更リスト（Change List, CL）への参照を削除するコマンド。
  • LGTM: "Looks Good To Me" の略で、コードレビューにおいて変更が承認されたことを意味します。
  • hg submit: 変更をMercurialリポジトリにコミット（提出）するコマンド。
  • hg clpatch: 変更リストを適用するコマンド。

ドキュメントの重要性

ソフトウェアプロジェクトにおいて、ドキュメントは非常に重要です。特に、貢献ガイドラインのようなドキュメントは、新規開発者がプロジェクトに参加し、コードベースに貢献するための障壁を下げる役割を果たします。正確で読みやすいドキュメントは、開発者の生産性を向上させ、プロジェクトの健全な成長を促進します。

技術的詳細

このコミットは、doc/contribute.html ファイル内の以下の箇所に焦点を当てています。

  1. <code> タグの修正:

    • 変更前: the remainder of this \n+document assumes you are inside <code>$GOROOT</code>, the remainder of this
    • 変更後: the remainder of this\n+document assumes you are inside <code>$GOROOT</code>, the remainder of this
    • ここでは、this の後に余分なスペースがあり、その後に改行と document が続いていました。この余分なスペースが削除され、HTMLの構造がよりクリーンになりました。

  2. 余分なスペースの削除:

    • 変更前: leaving stale references to closed or abandoned CLs. \n+You can use <code>hg change -D 99999</code> to remove the reference to CL 99999.
    • 変更後: leaving stale references to closed or abandoned CLs.\n+You can use <code>hg change -D 99999</code> to remove the reference to CL 99999.
    • ここでも、行末の余分なスペースが削除されています。

  3. <p> タグの追加と配置の修正:

    • 変更前: You can use <code>hg change -D 99999</code> to remove the reference to CL 99999. の後に </p> がなく、次の <h3> タグがすぐに続いていました。
    • 変更後: You can use <code>hg change -D 99999</code> to remove the reference to CL 99999.\n+</p> となり、適切な位置に </p> タグが追加されました。これにより、前の段落が正しく閉じられ、HTMLの構造がよりセマンティックになりました。

  4. <code> タグの修正:

    • 変更前: it to the Mercurial repository. \n+
    • 変更後: it to the Mercurial repository.\n+
    • ここでも、行末の余分なスペースが削除されています。

  5. <code> タグ内のスペース修正:

    • 変更前: <code>hg submit</code>\n-will refuse the change:
    • 変更後: <code>hg submit</code> will refuse the change:
    • <code>hg submit</code> の後にあった改行とハイフンが削除され、will refuse the change: が同じ行に続くように修正されました。これにより、hg submit コマンドとその結果に関する説明がより自然な形でつながるようになりました。

これらの変更は、HTMLの構文的な正確性を高め、結果としてブラウザでのレンダリング品質を向上させます。特に、コードスニペットやコマンドを囲む <code> タグの正確な使用は、技術ドキュメントの明瞭さにとって不可欠です。余分なスペースの削除は、コードのクリーンアップとファイルサイズのわずかな削減にも貢献します。

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

diff --git a/doc/contribute.html b/doc/contribute.html
index caff6ce20e..9d347fc0d7 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -113,7 +113,7 @@ you are a committer (see below), but Mercurial complains if it is missing.\n <p>\n After adding the extension, <code>hg help codereview</code>\n will show documentation for its commands. As the codereview extension is only\n-enabled for your checkout in <code>$GOROOT</code>, the remainder of this \n+enabled for your checkout in <code>$GOROOT</code>, the remainder of this\n document assumes you are inside <code>$GOROOT</code> when issuing commands.\n </p>\n \n@@ -522,14 +522,15 @@ be an effective way of reverting one CL revision and applying another.\n <p>\n Once the CL has been submitted, the next time you run <code>hg sync</code>\n it will be removed from your local pending list. Occasionally the pending list\n-can get out of sync leaving stale references to closed or abandoned CLs. \n+can get out of sync leaving stale references to closed or abandoned CLs.\n You can use <code>hg change -D 99999</code> to remove the reference to CL 99999.\n+</p>\n \n <h3>Submit the change after the review</h3>\n \n <p>\n After the code has been <code>LGTM</code>\'ed, it is time to submit\n-it to the Mercurial repository. \n+it to the Mercurial repository.\n </p>\n \n <p>\n@@ -543,6 +544,7 @@ $ hg clpatch 99999\n $ hg submit 99999\n </pre>\n \n+<p>\n The <code>submit</code> command submits the code.  You will be listed as the\n author, but the change message will also indicate who the committer was.\n Your local client will notice that the change has been submitted\n@@ -566,8 +568,7 @@ in the repository.\n \n <p>\n If your local copy of the repository is out of date,\n-<code>hg submit</code>\n-will refuse the change:\n+<code>hg submit</code> will refuse the change:\n </p>\n \n <pre>\n```

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

上記のdiffは、`doc/contribute.html` ファイルに対する変更を示しています。

- **行 113-114**:
    - `-enabled for your checkout in <code>$GOROOT</code>, the remainder of this \n`
    - `+enabled for your checkout in <code>$GOROOT</code>, the remainder of this\n`
    - `this` の後の余分なスペースが削除されました。これにより、HTMLのソースコードがよりクリーンになります。

- **行 522-524**:
    - `-can get out of sync leaving stale references to closed or abandoned CLs. \n`
    - `+can get out of sync leaving stale references to closed or abandoned CLs.\n`
    - `CLs.` の後の余分なスペースが削除されました。
    - `You can use <code>hg change -D 99999</code> to remove the reference to CL 99999.\n`
    - `+<p>\n`
    - 既存の段落の後に、新しい `<p>` タグが追加されました。これは、前の段落を適切に閉じ、次のセクション（`<h3>Submit the change after the review</h3>`）との間に適切な段落区切りを設けるためです。これにより、HTMLのセマンティクスが改善されます。

- **行 530-531**:
    - `-it to the Mercurial repository. \n`
    - `+it to the Mercurial repository.\n`
    - `repository.` の後の余分なスペースが削除されました。

- **行 543-544**:
    - `+<p>\n`
    - `The <code>submit</code> command submits the code.` の前に新しい `<p>` タグが追加されました。これは、前の `<pre>` タグで囲まれたコードブロックの後に、新しい段落を開始するためです。

- **行 566-568**:
    - `-<code>hg submit</code>\n-will refuse the change:\n`
    - `+<code>hg submit</code> will refuse the change:\n`
    - `<code>hg submit</code>` の後にあった改行とハイフンが削除され、`will refuse the change:` が同じ行に続くように修正されました。これにより、`hg submit` コマンドが変更を拒否する状況に関する説明が、より自然な文章の流れになりました。

これらの変更は全体として、`doc/contribute.html` のHTML構造を改善し、レンダリングされたドキュメントの可読性と正確性を向上させることを目的としています。

## 関連リンク

- Go言語公式ウェブサイト: [https://golang.org/](https://golang.org/)
- Go言語の貢献ガイドライン（現在のもの）: [https://go.dev/doc/contribute](https://go.dev/doc/contribute) (このコミットが修正したドキュメントの現在のバージョン)

## 参考にした情報源リンク

- GitHubコミットページ: [https://github.com/golang/go/commit/aecbcd0914bb99553862071ffeb0b355b8907f34](https://github.com/golang/go/commit/aecbcd0914bb99553862071ffeb0b355b8907f34)
- HTMLの基本（MDN Web Docs）: [https://developer.mozilla.org/ja/docs/Web/HTML](https://developer.mozilla.org/ja/docs/Web/HTML)
- Mercurial公式ウェブサイト: [https://www.mercurial-scm.org/](https://www.mercurial-scm.org/)
- Go言語のコードレビュープロセスに関する情報（古い情報を含む可能性あり）: [https://go.dev/doc/contribute#code_review](https://go.dev/doc/contribute#code_review) (現在の貢献ガイドラインの一部)