Add a help page with common workflows

7 files changed, 120 insertions, 0 deletions

diff --git a/source/cgit.c b/source/cgit.cindex caa90de..ce8b340 100644--- a/source/cgit.c+++ b/source/cgit.c@@ -183,6 +183,8 @@ static void config_cb(const char *name, const char *value) 		ctx.cfg.enable_filter_overrides = atoi(value); 	else if (!strcmp(name, "enable-follow-links")) 		ctx.cfg.enable_follow_links = atoi(value);+	else if (!strcmp(name, "enable-help"))+		ctx.cfg.enable_help = atoi(value); 	else if (!strcmp(name, "enable-http-clone")) 		ctx.cfg.enable_http_clone = atoi(value); 	else if (!strcmp(name, "enable-index-links"))@@ -406,6 +408,7 @@ static void prepare_context(void) 	ctx.cfg.logo = "/cgit.png"; 	ctx.cfg.favicon = "/favicon.ico"; 	ctx.cfg.local_time = 0;+	ctx.cfg.enable_help = 1; 	ctx.cfg.enable_http_clone = 1; 	ctx.cfg.enable_index_owner = 1; 	ctx.cfg.enable_tree_linenumbers = 1;
diff --git a/source/cgit.c b/source/cgit.c
index caa90de..ce8b340 100644
--- a/source/cgit.c
+++ b/source/cgit.c
@@ -183,6 +183,8 @@ static void config_cb(const char *name, const char *value)
 		ctx.cfg.enable_filter_overrides = atoi(value);
 	else if (!strcmp(name, "enable-follow-links"))
 		ctx.cfg.enable_follow_links = atoi(value);
+	else if (!strcmp(name, "enable-help"))
+		ctx.cfg.enable_help = atoi(value);
 	else if (!strcmp(name, "enable-http-clone"))
 		ctx.cfg.enable_http_clone = atoi(value);
 	else if (!strcmp(name, "enable-index-links"))
@@ -406,6 +408,7 @@ static void prepare_context(void)
 	ctx.cfg.logo = "/cgit.png";
 	ctx.cfg.favicon = "/favicon.ico";
 	ctx.cfg.local_time = 0;
+	ctx.cfg.enable_help = 1;
 	ctx.cfg.enable_http_clone = 1;
 	ctx.cfg.enable_index_owner = 1;
 	ctx.cfg.enable_tree_linenumbers = 1;
diff --git a/source/cgit.h b/source/cgit.hindex 5de7968..d921e76 100644--- a/source/cgit.h+++ b/source/cgit.h@@ -229,6 +229,7 @@ struct cgit_config { 	int embedded; 	int enable_filter_overrides; 	int enable_follow_links;+	int enable_help; 	int enable_http_clone; 	int enable_index_links; 	int enable_index_owner;
diff --git a/source/cgit.h b/source/cgit.h
index 5de7968..d921e76 100644
--- a/source/cgit.h
+++ b/source/cgit.h
@@ -229,6 +229,7 @@ struct cgit_config {
 	int embedded;
 	int enable_filter_overrides;
 	int enable_follow_links;
+	int enable_help;
 	int enable_http_clone;
 	int enable_index_links;
 	int enable_index_owner;
diff --git a/source/cgit.mk b/source/cgit.mkindex 1e5b5e1..ace8fd1 100644--- a/source/cgit.mk+++ b/source/cgit.mk@@ -90,6 +90,7 @@ CGIT_OBJ_NAMES += ui-blob.o CGIT_OBJ_NAMES += ui-clone.o CGIT_OBJ_NAMES += ui-commit.o CGIT_OBJ_NAMES += ui-diff.o+CGIT_OBJ_NAMES += ui-help.o CGIT_OBJ_NAMES += ui-log.o CGIT_OBJ_NAMES += ui-patch.o CGIT_OBJ_NAMES += ui-plain.o
diff --git a/source/cgit.mk b/source/cgit.mk
index 1e5b5e1..ace8fd1 100644
--- a/source/cgit.mk
+++ b/source/cgit.mk
@@ -90,6 +90,7 @@ CGIT_OBJ_NAMES += ui-blob.o
 CGIT_OBJ_NAMES += ui-clone.o
 CGIT_OBJ_NAMES += ui-commit.o
 CGIT_OBJ_NAMES += ui-diff.o
+CGIT_OBJ_NAMES += ui-help.o
 CGIT_OBJ_NAMES += ui-log.o
 CGIT_OBJ_NAMES += ui-patch.o
 CGIT_OBJ_NAMES += ui-plain.o
diff --git a/source/cmd.c b/source/cmd.cindex 477bb3f..a8768eb 100644--- a/source/cmd.c+++ b/source/cmd.c@@ -23,6 +23,7 @@ #include "ui-repolist.h" #include "ui-snapshot.h" #include "ui-stats.h"+#include "ui-help.h" #include "ui-summary.h" #include "ui-tag.h" #include "ui-tree.h"@@ -32,6 +33,14 @@ static void HEAD_fn(void) 	cgit_clone_head(); } +static void help_fn(void)+{+	if (ctx.cfg.enable_help)+		cgit_print_help();+	else+		cgit_print_error_page(404, "Not found", "Help is disabled");+}+ static void atom_fn(void) { 	cgit_print_atom(ctx.qry.head, ctx.qry.path, ctx.cfg.max_atom_items);@@ -184,6 +193,7 @@ struct cgit_cmd *cgit_get_cmd(void) 		def_cmd(blob, 1, 0, 0), 		def_cmd(commit, 1, 1, 0), 		def_cmd(diff, 1, 1, 0),+		def_cmd(help, 0, 0, 0), 		def_cmd(info, 1, 0, 1), 		def_cmd(log, 1, 1, 0), 		def_cmd(ls_cache, 0, 0, 0),
diff --git a/source/cmd.c b/source/cmd.c
index 477bb3f..a8768eb 100644
--- a/source/cmd.c
+++ b/source/cmd.c
@@ -23,6 +23,7 @@
 #include "ui-repolist.h"
 #include "ui-snapshot.h"
 #include "ui-stats.h"
+#include "ui-help.h"
 #include "ui-summary.h"
 #include "ui-tag.h"
 #include "ui-tree.h"
@@ -32,6 +33,14 @@ static void HEAD_fn(void)
 	cgit_clone_head();
 }
 
+static void help_fn(void)
+{
+	if (ctx.cfg.enable_help)
+		cgit_print_help();
+	else
+		cgit_print_error_page(404, "Not found", "Help is disabled");
+}
+
 static void atom_fn(void)
 {
 	cgit_print_atom(ctx.qry.head, ctx.qry.path, ctx.cfg.max_atom_items);
@@ -184,6 +193,7 @@ struct cgit_cmd *cgit_get_cmd(void)
 		def_cmd(blob, 1, 0, 0),
 		def_cmd(commit, 1, 1, 0),
 		def_cmd(diff, 1, 1, 0),
+		def_cmd(help, 0, 0, 0),
 		def_cmd(info, 1, 0, 1),
 		def_cmd(log, 1, 1, 0),
 		def_cmd(ls_cache, 0, 0, 0),
diff --git a/source/ui-help.c b/source/ui-help.cnew file mode 100644index 0000000..981733d--- /dev/null+++ b/source/ui-help.c@@ -0,0 +1,93 @@+/* ui-help.c: built-in guide to the cgit interface+ *+ * Copyright (C) 2006-2018 cgit Development Team <cgit@lists.zx2c4.com>+ *+ * Licensed under GNU General Public License v2+ *   (see LICENSE.txt for full license text)+ */++#include "cgit.h"+#include "ui-help.h"+#include "html.h"+#include "ui-shared.h"++static void print_workflow(const char *title, const char *intro,+			   const char *pattern, const char *example)+{+	html("<h2>");+	html_txt(title);+	html("</h2>\n<p>");+	html_txt(intro);+	html("</p>\n");+	if (pattern) {+		html("<pre class='urls'>");+		html_txt(pattern);+		if (example) {+			html("\n");+			html_txt(example);+		}+		html("</pre>\n");+	}+}++void cgit_print_help(void)+{+	cgit_print_layout_start();+	html("<div class='help'>\n");++	html("<p>Every page on this site has a stable address, so anything "+	     "you can see can also be linked, scripted or fetched. The "+	     "patterns below cover the common workflows. Angle brackets "+	     "mark the parts you replace.</p>\n");++	print_workflow("Browse a repository",+		"Each repository has a summary page, and the tabs on it lead "+		"to the branch and tag list, the commit history and the file "+		"tree.",+		"/<repo>/    /<repo>/refs/    /<repo>/log/    /<repo>/tree/",+		NULL);++	print_workflow("Pin what you are looking at",+		"Add h= to select a branch, or id= to select any commit, tag "+		"or object hash. They work on nearly every page, so a pinned "+		"URL always shows the same content.",+		"/<repo>/tree/?h=<branch>    /<repo>/tree/?id=<commit>",+		"/linux/tree/?h=stable      /linux/tree/?id=v6.1");++	print_workflow("View a file",+		"Append a path to the tree page for the rendered view, use "+		"plain for the raw bytes, and blame to see which commit last "+		"touched each line.",+		"/<repo>/tree/<path>    /<repo>/plain/<path>    /<repo>/blame/<path>",+		"/linux/tree/kernel/fork.c?h=v6.1");++	print_workflow("Compare two points in history",+		"The diff page compares id2, the older point, with id, the "+		"newer one. Both accept tags, branches and commit hashes. "+		"Use rawdiff for the plain patch text.",+		"/<repo>/diff/?id=<new>&id2=<old>",+		"/linux/diff/?id=v6.2&id2=v6.1");++	print_workflow("Follow the history of a path",+		"The log page takes a path to limit history to it. The "+		"search box above the log searches the message, author or "+		"committer, and the range type accepts any revision range.",+		"/<repo>/log/<path>    /<repo>/log/?qt=range&q=<rev1>..<rev2>",+		"/linux/log/?qt=range&q=v6.1..v6.2");++	print_workflow("Download a release or a patch",+		"Snapshots are archives of a tag or commit, named after the "+		"repository and version. The patch page emits a single "+		"commit as an emailable patch.",+		"/<repo>/snapshot/<repo>-<version>.tar.gz    /<repo>/patch/?id=<commit>",+		"/linux/snapshot/linux-v6.1.tar.gz");++	print_workflow("Subscribe to changes",+		"Every repository serves an Atom feed of its history, and "+		"h= scopes it to a branch.",+		"/<repo>/atom/    /<repo>/atom/?h=<branch>",+		NULL);++	html("</div>\n");+	cgit_print_layout_end();+}
diff --git a/source/ui-help.c b/source/ui-help.c
new file mode 100644
index 0000000..981733d
--- /dev/null
+++ b/source/ui-help.c
@@ -0,0 +1,93 @@
+/* ui-help.c: built-in guide to the cgit interface
+ *
+ * Copyright (C) 2006-2018 cgit Development Team <cgit@lists.zx2c4.com>
+ *
+ * Licensed under GNU General Public License v2
+ *   (see LICENSE.txt for full license text)
+ */
+
+#include "cgit.h"
+#include "ui-help.h"
+#include "html.h"
+#include "ui-shared.h"
+
+static void print_workflow(const char *title, const char *intro,
+			   const char *pattern, const char *example)
+{
+	html("<h2>");
+	html_txt(title);
+	html("</h2>\n<p>");
+	html_txt(intro);
+	html("</p>\n");
+	if (pattern) {
+		html("<pre class='urls'>");
+		html_txt(pattern);
+		if (example) {
+			html("\n");
+			html_txt(example);
+		}
+		html("</pre>\n");
+	}
+}
+
+void cgit_print_help(void)
+{
+	cgit_print_layout_start();
+	html("<div class='help'>\n");
+
+	html("<p>Every page on this site has a stable address, so anything "
+	     "you can see can also be linked, scripted or fetched. The "
+	     "patterns below cover the common workflows. Angle brackets "
+	     "mark the parts you replace.</p>\n");
+
+	print_workflow("Browse a repository",
+		"Each repository has a summary page, and the tabs on it lead "
+		"to the branch and tag list, the commit history and the file "
+		"tree.",
+		"/<repo>/    /<repo>/refs/    /<repo>/log/    /<repo>/tree/",
+		NULL);
+
+	print_workflow("Pin what you are looking at",
+		"Add h= to select a branch, or id= to select any commit, tag "
+		"or object hash. They work on nearly every page, so a pinned "
+		"URL always shows the same content.",
+		"/<repo>/tree/?h=<branch>    /<repo>/tree/?id=<commit>",
+		"/linux/tree/?h=stable      /linux/tree/?id=v6.1");
+
+	print_workflow("View a file",
+		"Append a path to the tree page for the rendered view, use "
+		"plain for the raw bytes, and blame to see which commit last "
+		"touched each line.",
+		"/<repo>/tree/<path>    /<repo>/plain/<path>    /<repo>/blame/<path>",
+		"/linux/tree/kernel/fork.c?h=v6.1");
+
+	print_workflow("Compare two points in history",
+		"The diff page compares id2, the older point, with id, the "
+		"newer one. Both accept tags, branches and commit hashes. "
+		"Use rawdiff for the plain patch text.",
+		"/<repo>/diff/?id=<new>&id2=<old>",
+		"/linux/diff/?id=v6.2&id2=v6.1");
+
+	print_workflow("Follow the history of a path",
+		"The log page takes a path to limit history to it. The "
+		"search box above the log searches the message, author or "
+		"committer, and the range type accepts any revision range.",
+		"/<repo>/log/<path>    /<repo>/log/?qt=range&q=<rev1>..<rev2>",
+		"/linux/log/?qt=range&q=v6.1..v6.2");
+
+	print_workflow("Download a release or a patch",
+		"Snapshots are archives of a tag or commit, named after the "
+		"repository and version. The patch page emits a single "
+		"commit as an emailable patch.",
+		"/<repo>/snapshot/<repo>-<version>.tar.gz    /<repo>/patch/?id=<commit>",
+		"/linux/snapshot/linux-v6.1.tar.gz");
+
+	print_workflow("Subscribe to changes",
+		"Every repository serves an Atom feed of its history, and "
+		"h= scopes it to a branch.",
+		"/<repo>/atom/    /<repo>/atom/?h=<branch>",
+		NULL);
+
+	html("</div>\n");
+	cgit_print_layout_end();
+}
diff --git a/source/ui-help.h b/source/ui-help.hnew file mode 100644index 0000000..85a4db7--- /dev/null+++ b/source/ui-help.h@@ -0,0 +1,6 @@+#ifndef UI_HELP_H+#define UI_HELP_H++extern void cgit_print_help(void);++#endif /* UI_HELP_H */
diff --git a/source/ui-help.h b/source/ui-help.h
new file mode 100644
index 0000000..85a4db7
--- /dev/null
+++ b/source/ui-help.h
@@ -0,0 +1,6 @@
+#ifndef UI_HELP_H
+#define UI_HELP_H
+
+extern void cgit_print_help(void);
+
+#endif /* UI_HELP_H */
diff --git a/source/ui-shared.c b/source/ui-shared.cindex df7ad1f..61ce3ca 100644--- a/source/ui-shared.c+++ b/source/ui-shared.c@@ -1192,6 +1192,12 @@ void cgit_print_pageheader(void) 				  NULL, NULL, 0, 1); 			html("</li>\n"); 		}+		if (ctx.cfg.enable_help) {+			html("<li>");+			site_link("help", "help", "How to use this site", hc("help"),+				  NULL, NULL, 0, 1);+			html("</li>\n");+		} 		html("</ul>\n"); 		html("<form class='search' method='get' action='"); 		html_attr(currenturl);
diff --git a/source/ui-shared.c b/source/ui-shared.c
index df7ad1f..61ce3ca 100644
--- a/source/ui-shared.c
+++ b/source/ui-shared.c
@@ -1192,6 +1192,12 @@ void cgit_print_pageheader(void)
 				  NULL, NULL, 0, 1);
 			html("</li>\n");
 		}
+		if (ctx.cfg.enable_help) {
+			html("<li>");
+			site_link("help", "help", "How to use this site", hc("help"),
+				  NULL, NULL, 0, 1);
+			html("</li>\n");
+		}
 		html("</ul>\n");
 		html("<form class='search' method='get' action='");
 		html_attr(currenturl);