Much improved ikiwiki structuring documentation.

3 files changed, 294 insertions, 118 deletions

diff --git a/ikisystem.mdwn b/ikisystem.mdwn
deleted file mode 100644
index f9424b7..0000000
--- a/ikisystem.mdwn
+++ /dev/null
@@ -1,118 +0,0 @@
-# Ikiwiki system configuration
-
-This website is powered by Ikiwiki. But instead of the normal Ikiwiki setup,
-each edit results in 2 parallel websites being built - one served purely static
-and one password-protected serving the static pages + CGI to edit them.
-
-Here's a graph of the interaction between the various parts of ikiwiki itself
-and different kinds of users:
-
-[[graph height=8 width=8 src="""
-{
-//	rankdir=LR
-//	rotate=90
-	center=1
-
-	{rank=same; user author designer}
-//	{rank=same; search_query txt_author txt_designer tmpl media}
-	subgraph cluster_clitools {
-		label="Commandline editing"
-		style=dashed
-		txt_designer
-		tmpl
-		media
-		vcs_tmpl_local
-		vcs_txt_local
-		fs_local
-	}
-	subgraph cluster_webtools {
-		label="Web editing"
-		style=dashed
-		txt_author
-		search_query
-		{
-			rank=same
-			browser_user
-			browser_author
-			browser_designer
-		}
-	}
-	{rank=same; search_form txt_form}
-//	{rank=same; txt_stored media_stored tmpl_stored}
-//	{rank=same; search_db vcs_txt vcs_tmpl fs}
-	subgraph cluster_storage {
-		label="Server storage"
-		style=dashed
-		vcs_tmpl
-		vcs_txt
-		fs
-		search_db
-		txt_stored
-		tmpl_stored
-		media_stored
-	}
-	{rank=same; iki_engine search_engine}
-	{rank=same; webpages webpages_admin webpages_searchresult}
-
-	/* roles */
-	user [shape=house, label="Any user"]
-	author [shape=house, label="Author"]
-	designer [shape=house, label="Web designer"]
-
-	/* input data types */
-	search_query [shape=plaintext, label="Search query"]
-	txt_author [shape=plaintext, label="Markdown text"]
-	txt_designer [shape=plaintext, label="Markdown text"]
-	media [shape=plaintext, label="Graphics files"]
-	tmpl [shape=plaintext, label="Html templates"]
-
-	browser_user [label="Web browser"]
-	browser_author [label="Web browser"]
-	browser_designer [label="Web browser"]
-	vcs_txt_local [shape=egg, label="Git repository"]
-	vcs_tmpl_local [shape=egg, label="Git repository"]
-	fs_local [shape=egg, label="Filesystem"]
-
-	txt_form [shape=box, label="Web text editor (Ikiwiki)"]
-	search_form [shape=box, label="Search form (Ikiwiki)"]
-	search_db [shape=egg, label="Search index (Hyper Estraier)"]
-	vcs_txt [shape=egg, label="VCS repository (Git)"]
-	vcs_tmpl [shape=egg, label="VCS repository (Git)"]
-	fs [shape=egg, label="Filesystem"]
-
-	/* stored data types */
-	txt_stored [shape=plaintext, label="Version-controlled Markdown text"]
-	media_stored [shape=plaintext, label="Graphics files"]
-	tmpl_stored [shape=plaintext, label="Version-controlled html templates"]
-
-	iki_engine [shape=box, label="Html renderer (Ikiwiki)"]
-	search_engine [shape=box, label="Search engine (Hyper Estraier)"]
-	webpages [label="Plain web pages"]
-	webpages_admin [label="Wiki pages"]
-	webpages_searchresult [label="Search results", style=dotted]
-
-	user -> search_query -> browser_user -> search_form -> search_engine -> webpages_searchresult
-	search_db -> search_engine
-	search_db -> iki_engine [dir=back]
-
-	author -> txt_author -> browser_author -> txt_form -> vcs_txt -> txt_stored -> iki_engine -> webpages
-	iki_engine -> webpages_admin
-
-	designer -> txt_designer -> browser_designer -> txt_form
-	txt_designer -> vcs_txt_local
-
-	vcs_txt_local -> vcs_txt [dir=both]
-
-	designer -> tmpl -> vcs_tmpl_local
-	vcs_tmpl_local -> vcs_tmpl [dir=both]
-	vcs_tmpl -> tmpl_stored -> iki_engine
-
-	designer -> media -> fs_local
-	fs_local -> fs [dir=both]
-	fs -> media_stored -> iki_engine
-}
-"""]]
-
-----
-
-See also the simpler graphs focusing on [[roles|ikiroles]] and on the [[design|ikidesign]].
diff --git a/ikiwiki.mdwn b/ikiwiki.mdwn
new file mode 100644
index 0000000..2c03a37
--- /dev/null
+++ b/ikiwiki.mdwn
@@ -0,0 +1,11 @@
+# Ikiwiki
+
+This website is powered by [Ikiwiki](http://ikiwiki.info).
+
+Ikiwiki is a [[wiki_compiler|compiler]].
+
+Ikiwiki is not only useful to build a [[wiki]]. It is also great to
+administrate a regular websites|website]] and more complex blog-related
+sites.
+
+Ikiwiki can handle several kinds of [[multi-language_websites|multilang]].
diff --git a/ikiwiki/website.mdwn b/ikiwiki/website.mdwn
new file mode 100644
index 0000000..d6b0711
--- /dev/null
+++ b/ikiwiki/website.mdwn
@@ -0,0 +1,283 @@
+# Ikiwiki for regular websites
+
+[[Ikiwiki]] can be used to administrate regular websites.
+
+## Introduction
+
+Websites built with ikiwiki is more complex than plain static websites,
+but simpler than most web-based content management systems (CMS).
+
+One of the benefits over using static webpages is that text content can
+be edited independent of the webdesign.  This means, that...
+
+ * The editor (e.g. owner of the website or a secretary) need not bother
+   the web designer with text-only changes.
+ * The editor can start adding text content even before the visual
+   design is finalized.
+
+One of the benefits compared to using most other CMS or wiki engines is
+that most pages are served as static html.
+
+## Roles
+
+Wiki sites classically is public.  Anyone can both read the site and
+edit its pages.
+
+A regular website is meant to only be edited by som website
+administrator.
+
+Ikiwiki offers the possibility to separate different administration
+tasks.  You need not be a webdesigner to edit text content, and you need
+not be limited by the user-friendly text editing interface as a web
+designer.
+
+[[graph height=8 width=8 src="""
+{
+	/* roles */
+	reader [shape=house, label="Reader"]
+	editor [shape=house, label="Editor"]
+	designer [shape=house, label="Designer"]
+	{rank=same; reader editor designer}
+
+	/* targets */
+	webpages_static [label="website"]
+	webpages_wiki [label="admin website"]
+	{rank=same; webpages_static webpages_wiki}
+
+	/* input data */
+	txt [shape=plaintext, label="text"]
+	media [shape=plaintext, label="graphics"]
+	tmpl [shape=plaintext, label="templates"]
+	{rank=same; txt tmpl media}
+
+	iki_engine [shape=box, label="web engine"]
+
+	/* paths */
+	reader -> webpages_static [dir=back]
+	editor -> txt -> iki_engine -> webpages_wiki
+	designer -> media -> iki_engine
+	designer -> tmpl -> iki_engine
+	iki_engine -> webpages_static
+}
+"""]]
+
+## Reader
+
+The reader gets served a static website:
+
+[[graph height=8 width=8 src="""
+{
+	reader [shape=house, label="Reader"]
+
+	webpages_static [label="static pages"]
+
+	reader -> webpages_static
+}
+"""]]
+
+The website can have a search routine added.
+
+The reader then interacts both with static pages and with a search
+engine, dynamically generating search result pages:
+
+[[graph height=8 width=8 src="""
+{
+	reader [shape=house, label="Reader"]
+
+	/* targets */
+	webpages_static [label="static pages"]
+	webpages_searchresult [label="search results", style=dotted]
+	{rank=same; webpages_static webpages_searchresult}
+
+	search_query [shape=plaintext, label="search query"]
+
+	search_db [shape=box, label="search index"]
+
+	/* paths */
+	reader -> webpages_static
+	reader -> search_query -> search_db -> webpages_searchresult
+}
+"""]]
+
+## Editor
+
+In addition to the main website, an additional website is generated,
+with the main feature of Ikiwiki - [[wiki]]-like text editing - enabled:
+
+[[graph height=8 width=8 src="""
+{
+	editor [shape=house, label="Editor"]
+
+	webpages_wiki [label="wiki pages"]
+
+	content_form [shape=plaintext, label="edit form"]
+
+	/* stored data */
+	txt_stored [shape=box, label="text content"]
+	media_stored [shape=box, label="graphics files"]
+	tmpl_stored [shape=box, label="html templates"]
+	{rank=same; txt_stored media_stored tmpl_stored}
+
+	/* paths */
+	editor -> webpages_wiki
+	editor -> content_form -> txt_stored -> webpages_wiki
+	media_stored -> webpages_wiki
+	tmpl_stored -> webpages_wiki
+}
+"""]]
+
+Whenever the wiki pages are edited, the static pages are also rebuilt:
+
+[[graph height=8 width=8 src="""
+{
+	/* roles */
+	editor [shape=house, label="Editor"]
+
+	/* targets */
+	webpages_static [label="static pages"]
+	webpages_wiki [label="wiki pages"]
+	{rank=same; webpages_static webpages_wiki}
+
+	/* input data */
+	content_form [shape=plaintext, label="edit form"]
+
+	/* stored data */
+	txt_stored [shape=box, label="text content"]
+	media_stored [shape=box, label="graphics files"]
+	tmpl_stored [shape=box, label="html templates"]
+	{rank=same; txt_stored media_stored tmpl_stored}
+
+	iki_engine [shape=box, label="html renderer (ikiwiki)"]
+
+	/* paths */
+	editor -> content_form -> txt_stored -> iki_engine -> webpages_wiki
+	media_stored -> iki_engine
+	tmpl_stored -> iki_engine
+	iki_engine -> webpages_static
+}
+"""]]
+
+## All
+
+Here's a graph of the interaction between the various parts of ikiwiki itself
+and different kinds of users:
+
+[[graph height=8 width=8 src="""
+{
+//	rankdir=LR
+//	rotate=90
+	center=1
+
+	/* roles */
+	reader [shape=house, label="Reader"]
+	editor [shape=house, label="Editor"]
+	designer [shape=house, label="Designer"]
+	{rank=same; reader editor designer}
+
+	/* targets */
+	webpages [label="static pages"]
+	webpages_wiki [label="wiki pages"]
+	webpages_searchresult [label="search results", style=dotted]
+	{rank=same; webpages webpages_wiki webpages_searchresult}
+
+	/* input data */
+	search_query [shape=plaintext, label="search query"]
+	txt_editor [shape=plaintext, label="Markdown text"]
+	txt_designer [shape=plaintext, label="Markdown text"]
+	media [shape=plaintext, label="graphics files"]
+	tmpl [shape=plaintext, label="html templates"]
+//	{rank=same; search_query txt_editor txt_designer tmpl media}
+
+	/* user tool */
+	browser_reader [label="web browser"]
+	browser_editor [label="web browser"]
+	browser_designer [label="web browser"]
+	vcs_txt_local [shape=egg, label="Git repository"]
+	vcs_tmpl_local [shape=egg, label="Git repository"]
+	fs_local [shape=egg, label="filesystem"]
+
+	/* user interface */
+	txt_form [shape=box, label="web text editor (ikiwiki)"]
+	search_form [shape=box, label="search form (ikiwiki)"]
+	{rank=same; search_form txt_form}
+
+	/* storage types */
+	search_db [shape=egg, label="search index (Hyper Estraier)"]
+	vcs_txt [shape=egg, label="VCS repository (Git)"]
+	vcs_tmpl [shape=egg, label="VCS repository (Git)"]
+	fs [shape=egg, label="filesystem"]
+//	{rank=same; search_db vcs_txt vcs_tmpl fs}
+
+	/* stored data */
+	txt_stored [shape=plaintext, label="version-controlled Markdown text"]
+	media_stored [shape=plaintext, label="graphics files"]
+	tmpl_stored [shape=plaintext, label="version-controlled html templates"]
+//	{rank=same; txt_stored media_stored tmpl_stored}
+
+	/* engines */
+	iki_engine [shape=box, label="html renderer (Ikiwiki)"]
+	search_engine [shape=box, label="search engine (Hyper Estraier)"]
+	{rank=same; iki_engine search_engine}
+
+	/* groupings */
+	subgraph cluster_clitools {
+		label="commandline editing"
+		style=dashed
+		txt_designer
+		tmpl
+		media
+		vcs_tmpl_local
+		vcs_txt_local
+		fs_local
+	}
+	subgraph cluster_webtools {
+		label="web editing"
+		style=dashed
+		txt_editor
+		search_query
+		{
+			rank=same
+			browser_reader
+			browser_editor
+			browser_designer
+		}
+	}
+	subgraph cluster_storage {
+		label="server storage"
+		style=dashed
+		vcs_tmpl
+		vcs_txt
+		fs
+		search_db
+		txt_stored
+		tmpl_stored
+		media_stored
+	}
+
+	/* paths */
+
+	reader -> search_query -> browser_reader -> search_form -> search_engine -> webpages_searchresult
+	search_db -> search_engine
+	search_db -> iki_engine [dir=back]
+
+	editor -> txt_editor -> browser_editor -> txt_form -> vcs_txt -> txt_stored -> iki_engine -> webpages
+	iki_engine -> webpages_wiki
+
+	designer -> txt_designer -> browser_designer -> txt_form
+	txt_designer -> vcs_txt_local
+
+	vcs_txt_local -> vcs_txt [dir=both]
+
+	designer -> tmpl -> vcs_tmpl_local
+	vcs_tmpl_local -> vcs_tmpl [dir=both]
+	vcs_tmpl -> tmpl_stored -> iki_engine
+
+	designer -> media -> fs_local
+	fs_local -> fs [dir=both]
+	fs -> media_stored -> iki_engine
+}
+"""]]
+
+----
+
+See also the simpler graphs focusing on [[roles|ikiroles]] and on the [[design|ikidesign]].