/* 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();
}