From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <e@80x24.org>
X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net
X-Spam-Level: 
X-Spam-ASN:  
X-Spam-Status: No, score=-4.2 required=3.0 tests=ALL_TRUSTED,BAYES_00,
	DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,
	T_SCC_BODY_TEXT_LINE shortcircuit=no autolearn=ham autolearn_force=no
	version=3.4.2
Received: from localhost (dcvr.yhbt.net [127.0.0.1])
	by dcvr.yhbt.net (Postfix) with ESMTP id B0EC51F629
	for <meta@public-inbox.org>; Mon, 29 Aug 2022 09:26:49 +0000 (UTC)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=80x24.org;
	s=selector1; t=1661765209;
	bh=IGCHpZsb5PYaHg0MWjA88nTG9NQ9Qh/V1YZWNaKsduU=;
	h=From:To:Subject:Date:In-Reply-To:References:From;
	b=MTYTqVppzfaORklzLjkwgjWzjrtLOPc8yBEw6a+opEGDgaHmvW9nCrkVTzhTFnLAX
	 TRX0XW0jkF3pyVNj4ShR2kOFCKxzsoXPUINjLLyHeP+ht5Z8TenkrEHkyv+sWGfAF3
	 7olsQblWCTd4AgvYNXVeMyIUoTvvav9xYlfe60Z0=
From: Eric Wong <e@80x24.org>
To: meta@public-inbox.org
Subject: [PATCH 17/18] viewvcs: add glossary for commit
Date: Mon, 29 Aug 2022 09:26:46 +0000
Message-Id: <20220829092647.1512215-18-e@80x24.org>
In-Reply-To: <20220829092647.1512215-1-e@80x24.org>
References: <20220829092647.1512215-1-e@80x24.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
List-Id: <meta.public-inbox.org>

IMHO, it's important to let users know on how commits tie trees
and parent commits together.
---
 lib/PublicInbox/ViewVCS.pm | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/lib/PublicInbox/ViewVCS.pm b/lib/PublicInbox/ViewVCS.pm
index 0a38f9de..4c4cf3b3 100644
--- a/lib/PublicInbox/ViewVCS.pm
+++ b/lib/PublicInbox/ViewVCS.pm
@@ -179,19 +179,19 @@ title="list contemporary emails">$2</a>)
 	$_ = qq(<a href="$upfx$_/s/">).shift(@$p).'</a> '.shift(@$pt) for @$P;
 	if (@$P == 1) {
 		$x = qq{ (<a
-href="$f.patch">patch</a>)\n   parent $P->[0]};
+href="$f.patch">patch</a>)\n   <a href=#parent>parent</a> $P->[0]};
 	} elsif (@$P > 1) {
-		$x = qq(\n  parents $P->[0]\n);
+		$x = qq(\n  <a href=#parents>parents</a> $P->[0]\n);
 		shift @$P;
 		$x .= qq(          $_\n) for @$P;
 		chop $x;
 	} else {
-		$x = ' (root commit)';
+		$x = ' (<a href=#root_commit>root commit</a>)';
 	}
 	PublicInbox::WwwStream::html_init($ctx);
 	$ctx->zmore(<<EOM);
-<pre>   commit $H$x
-     tree <a href="$upfx$T/s/">$T</a>
+<pre>   <a href=#commit>commit</a> $H$x
+     <a href=#tree>tree</a> <a href="$upfx$T/s/">$T</a>
    author $au
 committer $co
 
@@ -238,7 +238,23 @@ id=related><pre>find related emails, including ancestors/descendants/conflicts
 EOM
 		}
 	}
-	$x = $ctx->zflush($ctx->_html_end);
+	chop($x = <<EOM);
+<pre>glossary
+--------
+<dfn
+id=commit>Commit</dfn> objects reference one tree, and zero or more parents.
+
+Single <dfn
+id=parent>parent</dfn> commits can typically generate a patch in
+unified diff format via `git format-patch'.
+
+Multiple <dfn id=parents>parents</dfn> means the commit is a merge.
+<dfn id=root_commit>Root commits</a> have no ancestor.  Note that it is
+possible to have multiple root commits when merging independent histories.
+
+Every commit references one top-level <dfn id=tree>tree</dfn> object.</pre>
+EOM
+	$x = $ctx->zflush($x, $ctx->_html_end);
 	my $res_hdr = delete $ctx->{-res_hdr};
 	push @$res_hdr, 'Content-Length', length($x);
 	delete($ctx->{env}->{'qspawn.wcb'})->([200, $res_hdr, [$x]]);