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

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

このコミットは、Goプログラミング言語の仕様書ファイル go_spec.txt をHTML形式の go_spec.html へと変換し、ファイル名を変更するものです。本質的な仕様内容の変更はなく、主にドキュメントの可読性と構造化を向上させるためのフォーマット変更が目的です。これにより、仕様書がWebブラウザでより見やすく、ナビゲートしやすい形式で提供されるようになります。

コミット

  • コミットハッシュ: c2d5586c761b64314f3035b8e52e9f937413be53
  • Author: Robert Griesemer gri@golang.org
  • Date: Thu Feb 19 16:49:10 2009 -0800

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

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

元コミット内容

go_spec.txt formatted in html.
No textual changes except for html formatting.
Seems like a fine intermediate step.

R=r
DELTA=7638  (4079 added, 3559 deleted, 0 changed)
OCL=25211
CL=25224

変更の背景

Go言語の初期段階において、その言語仕様はプレーンテキストファイル go_spec.txt として管理されていました。しかし、プレーンテキスト形式では、以下のような点で限界がありました。

  1. 可読性の低さ: 長大なテキストファイルでは、セクションの区切りや強調表示が難しく、読者が内容を把握しにくい。
  2. ナビゲーションの困難さ: 特定のセクションへのジャンプや、関連する定義への参照ができないため、ドキュメント内を移動するのが非効率。
  3. 表現力の限界: 図や表、コード例のシンタックスハイライトなど、よりリッチな表現が不可能。

これらの課題を解決し、Go言語の仕様書をより多くの開発者にとってアクセスしやすく、理解しやすいものにするため、Webブラウザで表示可能なHTML形式への変換が決定されました。このコミットは、その変換プロセスの初期段階として、既存のテキスト内容を保持しつつ、基本的なHTMLタグを適用して構造化を行うものです。コミットメッセージにある「Seems like a fine intermediate step.」という記述は、これが最終的なフォーマットではなく、今後の改善を見据えた中間的なステップであることを示唆しています。

前提知識の解説

Go言語の仕様書 (go_spec.txt)

Go言語は、Googleによって開発された静的型付け、コンパイル型言語です。その設計思想は、シンプルさ、効率性、並行処理の容易さに重点を置いています。言語の挙動を厳密に定義するためには、詳細な仕様書が不可欠です。初期のGo言語開発において、この仕様書は go_spec.txt というプレーンテキストファイルとして作成され、言語の文法、型システム、組み込み関数、パッケージ構造などが記述されていました。これは、言語設計者や初期の貢献者が言語の定義を共有し、議論するための基礎資料でした。

プレーンテキスト (.txt)

.txt 拡張子を持つファイルは、特別な書式設定や構造を持たない純粋なテキストデータを格納します。メモ帳やテキストエディタで簡単に開いて編集できる汎用的な形式です。利点としては、高い互換性とシンプルさがありますが、前述の通り、複雑なドキュメントの表現には不向きです。

HTML (.html)

HTML (HyperText Markup Language) は、Webページを作成するための標準マークアップ言語です。HTMLは、テキストに構造と意味を与えるための「タグ」を使用します。例えば、見出し (<h1>, <h2>など)、段落 (<p>)、リスト (<ul>, <ol>, <li>)、コードブロック (<pre>, <code>)、ハイパーリンク (<a>) など、様々な要素を定義できます。これにより、ドキュメントの論理構造を明確にし、視覚的な表現を豊かにし、異なるセクション間や外部リソースへのナビゲーションを可能にします。WebブラウザはHTMLファイルを解釈し、整形されたWebページとして表示します。

EBNF (Extended Backus-Naur Form)

EBNFは、プログラミング言語や通信プロトコルなどの文法を記述するためのメタ言語（言語を記述するための言語）です。このコミットでHTML化された go_spec.txt の内容にも、Go言語の文法を定義するためにEBNFが多用されています。EBNFは、以下のような記号を用いて文法規則を表現します。

  • = : 定義
  • | : 選択（OR）
  • { ... } : 0回以上の繰り返し
  • [ ... ] : 0回または1回（オプション）
  • ( ... ) : グループ化
  • "..." : リテラル（終端記号）
  • production_name : 非終端記号（別の規則で定義される要素）

例えば、Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . は、Digit が0から9までのいずれかの文字であることを示します。EBNFを用いることで、言語の文法を曖昧さなく、簡潔に記述することができます。

技術的詳細

このコミットの主要な変更は、ファイルのリネームと内容のHTMLフォーマット化です。

  1. ファイルのリネーム: doc/go_spec.txt が doc/go_spec.html に変更されました。これは git diff の出力 rename from doc/go_spec.txt と rename to doc/go_spec.html から明確に読み取れます。

  2. 内容の変換と similarity index: git diff の出力には similarity index 69% と表示されています。これは、Gitが元のファイルと新しいファイルの類似度を計算した結果です。69%という値は、ファイルの内容が完全に書き換えられたわけではなく、元のテキストの大部分が保持されつつ、HTMLタグの追加やプレーンテキストの書式（例: ----- やインデント）がHTMLの構造に置き換えられたことを示しています。 DELTA=7638 (4079 added, 3559 deleted, 0 changed) という行は、この変更によって4079行が追加され、3559行が削除されたことを示しています。これは、プレーンテキストの行が削除され、その代わりにHTMLタグを含む新しい行が追加されたためです。例えば、セクションの区切りを示す ----- のような行が削除され、代わりに <h2> や <hr> といったHTMLタグが挿入されています。また、リストのインデントが <ul> や <li> タグに置き換えられたり、コード例が <pre> タグで囲まれたりしています。

  3. HTMLタグの導入: コミットの差分を見ると、以下のようなHTMLタグが導入されていることがわかります。

    • <h2>, <h3>: セクションの見出し。元のテキストの ----- で区切られた見出しがこれらに変換されています。
    • <ul>, <li>: 箇条書きリスト。元のテキストのインデントされた箇条書きがこれらに変換されています。
    • <pre>: 整形済みテキスト。特にEBNFの文法定義やコード例など、元のテキストの空白や改行をそのまま保持したい部分に適用されています。
    • <p>: 段落。テキストのブロックを段落として定義しています。
    • <hr>: 水平線。セクション間の区切りとして使用されています。
    • <font color=red>: 注意書きのテキストの色を変更するために使用されています。これはHTML4時代の記述であり、現代のWeb開発ではCSSでスタイルを適用するのが一般的です。

これらの変更により、仕様書はWebブラウザでレンダリングされた際に、より構造化され、視覚的に分かりやすいドキュメントとして表示されるようになります。

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

このコミットは、doc/go_spec.txt を doc/go_spec.html にリネームし、その内容をHTML形式に変換しています。以下に、その変更の具体的な例をいくつか示します。

1. ファイル名の変更:

--- a/doc/go_spec.txt
+++ b/doc/go_spec.html

2. ドキュメント冒頭のメタ情報と注意書きのHTML化:

@@ -1,22 +1,13 @@
-The Go Programming Language Specification (DRAFT)
------
-
-Russ Cox, Robert Griesemer, Rob Pike, Ian Taylor, Ken Thompson
-
-(February 11, 2009)
-
------
-
 This document is a semi-formal specification of the Go systems
 programming language.
-
+<p>
 <font color=red>
 This document is not ready for external review, it is under active development.
 Any part may change substantially as design progresses.
 </font>
-
------
-
 <!--
 Biggest open issues:
 [ ] General iterators
@@ -153,187 +144,216 @@ Timeline (9/5/08):
 -->

ここでは、元のテキストのヘッダー部分が削除され、HTMLの段落タグ <p> や <font> タグが導入されています。

3. 目次セクションのHTML化:

@@ -153,187 +144,216 @@ Timeline (9/5/08):
 -->


-Contents
------
-
-	Introduction
-		Guiding principles
-		Program structure
-		Modularity, identifiers and scopes
-		Typing, polymorphism, and object-orientation
-		Pointers and garbage collection
-		Values and references
-		Multithreading and channels
-
-	Notation
-
-	Source code representation
-		Characters
-		Letters and digits
-
-	Vocabulary
-		Identifiers
-		Numeric literals
-		Character and string literals
-		Operators and delimitors
-		Reserved words
-
-	Declarations and scope rules
-		Predeclared identifiers
-		Exported identifiers
-		Const declarations
-			Iota
-		Type declarations
-		Variable declarations
-
-	Types
-		Basic types
-			Arithmetic types
-			Booleans
-			Strings
-		Array types
-		Struct types
-		Pointer types
-		Function types
-		Interface types
-		Slice types
-		Map types
-		Channel types
-		Type equality
-
-	Expressions
-		Operands
-			Constants
-			Qualified identifiers
-			Composite literals
-			Function literals
-
-		Primary expressions
-			Selectors
-			Indexes
-			Slices
-			Type guards
-			Calls
-				Parameter passing
-
-		Operators
-			Arithmetic operators
-				Integer overflow
-			Comparison operators
-			Logical operators
-			Address operators
-			Communication operators
-
-		Constant expressions
-
-	Statements
-		Label declarations
-		Expression statements
-		IncDec statements
-		Assignments
-		If statements
-		Switch statements
-		For statements
-		Go statements
-		Select statements
-		Return statements
-		Break statements
-		Continue statements
-		Label declaration
-		Goto statements
-		Defer statements
-
-	Function declarations
-		Method declarations
-		Predeclared functions
-			Length and capacity
-		Conversions
-			Allocation
-			Making slices, maps, and channels
-
-	Packages
-
-	Program initialization and execution
-
-	Systems considerations
-		Package unsafe
-		Size and alignment guarantees


------

-Introduction
------
+<h2>Contents</h2>
+<ul>
+<li>Introduction
+	<ul>
+	<li>Guiding principles
+	<li>Program structure
+	<li>Modularity, identifiers and scopes
+	<li>Typing, polymorphism, and object-orientation
+	<li>Pointers and garbage collection
+	<li>Values and references
+	<li>Multithreading and channels
+	</ul>
+	
+<li>Notation
+
+<li>Source code representation
+	<ul>
+	<li>Characters
+	<li>Letters and digits
+	</ul>
+
+<li>Vocabulary
+	<ul>
+	<li>Identifiers
+	<li>Numeric literals
+	<li>Character and string literals
+	<li>Operators and delimitors
+	<li>Reserved words
+	</ul>
+
+<li>Declarations and scope rules
+	<ul>
+	<li>Predeclared identifiers
+	<li>Exported identifiers
+	<li>Const declarations
+		<ul>
+		<li>Iota
+		</ul>
+	<li>Type declarations
+	<li>Variable declarations
+	</ul>
+
+<li>Types
+	<ul>
+	<li>Basic types
+		<ul>
+		<li>Arithmetic types
+		<li>Booleans
+		<li>Strings
+		</ul>
+	<li>Array types
+	<li>Struct types
+	<li>Pointer types
+	<li>Function types
+	<li>Interface types
+	<li>Slice types
+	<li>Map types
+	<li>Channel types
+	<li>Type equality
+	</ul>
+
+<li>Expressions
+	<ul>
+	<li>Operands
+		<ul>
+		<li>Constants
+		<li>Qualified identifiers
+		<li>Composite literals
+		<li>Function literals
+		</ul>
+		
+	<li>Primary expressions
+		<ul>
+		<li>Selectors
+		<li>Indexes
+		<li>Slices
+		<li>Type guards
+		<li>Calls
+			<ul>
+			<li>Parameter passing
+			</ul>
+		</ul>
+		
+	<li>Operators
+		<ul>
+		<li>Arithmetic operators
+			<ul>
+			<li>Integer overflow
+			</ul>
+		<li>Comparison operators
+		<li>Logical operators
+		<li>Address operators
+		<li>Communication operators
+		</ul>
+		
+	<li>Constant expressions
+	</ul>
+
+<li>Statements
+	<ul>
+	<li>Label declarations
+	<li>Expression statements
+	<li>IncDec statements
+	<li>Assignments
+	<li>If statements
+	<li>Switch statements
+	<li>For statements
+	<li>Go statements
+	<li>Select statements
+	<li>Return statements
+	<li>Break statements
+	<li>Continue statements
+	<li>Label declaration
+	<li>Goto statements
+	<li>Defer statements
+	</ul>
+
+<li>Function declarations
+	<ul>
+	<li>Method declarations
+	<li>Predeclared functions
+		<ul>
+		<li>Length and capacity
+		<li>Conversions
+		<li>Allocation
+		<li>Making slices, maps, and channels
+		</ul>
+	</ul>
+
+<li>Packages
+
+<li>Program initialization and execution
+
+<li>Systems considerations
+	<ul>
+	<li>Package unsafe
+	<li>Size and alignment guarantees
+	</ul>
+</ul>
+
+<hr>
+
+<h2>Introduction</h2>

目次部分が、<h2>Contents</h2> で始まり、ネストされた <ul> と <li> タグで階層構造が表現されています。各セクションの開始を示す ----- は <hr> タグに置き換えられています。

4. EBNF定義のHTML化:

@@ -385,160 +403,163 @@ pointer to the map; thus the map contents are not copied when a map is assigned
 to a variable.\n
 \n \n-Multithreading and channels
------
+<h3>Multithreading and channels</h3>
 \n Go supports multithreaded programming directly. A function may\n
 be invoked as a parallel thread of execution.  Communication and\n
 synchronization are provided through channels and their associated\n
 language support.\n \n+<hr>\n \n------
-\n-Notation
------
+<h2>Notation</h2>
 \n The syntax is specified using Extended Backus-Naur Form (EBNF):\n \n-\tProduction = production_name \"=\" Expression .\n-\tExpression = Alternative { \"|\" Alternative } .\n-\tAlternative = Term { Term } .\n-\tTerm = production_name | token [ \"...\" token ] | Group | Option | Repetition .\n-\tGroup = \"(\" Expression \")\" .\n-\tOption = \"[\" Expression \")\" .\n-\tRepetition = \"{\" Expression \"}\" .\
+<pre>
+Production = production_name \"=\" Expression .\n+Expression = Alternative { \"|\" Alternative } .\n+Alternative = Term { Term } .\n+Term = production_name | token [ \"...\" token ] | Group | Option | Repetition .\n+Group = \"(\" Expression \")\" .\n+Option = \"[\" Expression \")\" .\n+Repetition = \"{\" Expression \"}\" .\
+</pre>
 \n Productions are expressions constructed from terms and the following operators:\n \n-\t|   separates alternatives (least binding strength)\n-\t()  groups\n-\t[]  specifies an option (0 or 1 times)\n-\t{}  specifies repetition (0 to n times)\
+<pre>
+|   separates alternatives (least binding strength)\n+()  groups\n+[]  specifies an option (0 or 1 times)\n+{}  specifies repetition (0 to n times)\n+</pre>

EBNFの定義やその説明部分が <pre> タグで囲まれています。これにより、元のテキストの整形（インデントや空白）がWebブラウザでも保持されるようになります。

コアとなるコードの解説

上記の変更箇所は、プレーンテキストの仕様書をWebフレンドリーなHTML形式に変換する際の典型的なパターンを示しています。

  • ファイル名変更: go_spec.txt から go_spec.html への変更は、ファイルがWebコンテンツとして扱われることを明確に示します。
  • ヘッダーと注意書き: 元のテキストのシンプルなヘッダーは削除され、HTMLの段落タグ <p> と、注意を促すための赤い文字 (<font color=red>) が導入されています。これにより、ドキュメントのタイトルや重要な警告が視覚的に強調されます。
  • 目次: プレーンテキストのインデントされた目次は、HTMLの <h2> (見出し) とネストされた <ul> (順序なしリスト) および <li> (リストアイテム) タグに変換されています。これにより、目次が構造化され、Webブラウザの機能（例: 開発者ツールでの要素の折りたたみ）を利用してナビゲートしやすくなります。
  • セクション区切り: 元のテキストでセクションの区切りとして使われていた ----- は、HTMLの <hr> (水平線) タグに置き換えられています。これは視覚的な区切りを提供し、セクションの開始を明確にします。
  • EBNFとコード例: EBNFの文法定義やコード例は、元のテキストの整形を保持するために <pre> (整形済みテキスト) タグで囲まれています。これにより、ブラウザがこれらの内容を固定幅フォントで表示し、空白や改行をそのまま維持するため、文法規則やコードの可読性が保たれます。

これらの変更は、Go言語の仕様書が単なるテキストファイルから、よりインタラクティブでアクセスしやすいWebドキュメントへと進化する第一歩でした。これにより、開発者は仕様書をより効率的に参照し、Go言語の理解を深めることができるようになりました。

関連リンク

参考にした情報源リンク

  • Go言語公式ドキュメント
  • Gitドキュメント (特に git diff コマンドと similarity index について)
  • HTMLの基本構造とタグに関する一般的なWeb開発リソース
  • EBNFに関する一般的な情報源