[Webapps-common-discuss] webapps-common/doc webapps-common.sgml, 1.1, 1.2

[seanius at haydn.debian.org]

Update of /cvsroot/webapps-common/webapps-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv16691/doc

Modified Files:
	webapps-common.sgml 
Log Message:
a little more work

Index: webapps-common.sgml
===================================================================
RCS file: /cvsroot/webapps-common/webapps-common/doc/webapps-common.sgml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- webapps-common.sgml	17 Oct 2005 11:04:50 -0000	1.1
+++ webapps-common.sgml	19 Oct 2005 14:53:19 -0000	1.2
@@ -7,19 +7,116 @@
 <version>
 	$Revision$
 <abstract>
-	webapps-common is an implementation of the "best practices for
-	web applications" draft, which provides debian packagers
+	webapps-common is an implementation of the "Best Practices for
+	Web Applications DRAFT", which provides debian packagers
 	with an easy, reliable, and consistant method for managing
 	issues related to web applications.  
 <copyright>
 	Copyright © 2005 sean finney <email>seanius at debian.org</email>.
 <toc sect1>
-<chapt id="foo">foo
+<chapt id="intro">Introduction
 	<p>
-	foo
-	<sect id="foo-bar">foo bar
+	As more and more web-accessible applications are being developed
+	and subsequently packaged in Debian, it is becoming increasingly
+	important to provide a common infrastructure for how these
+	applications should behave.  
 	<p>
-	foo bar
+	webapps-common aims to fill this niche, by providing a centralized
+	set of tools and procedures for configuring web applications,
+	webserver extensions, and other packages related to the world
+	of web applications.
+	<p>
+	With this in mind, webapps-common has been designed to:
+	<list>
+	<item>support the entire family of apache based webservers
+	<item>support "subdirectory" and "virtualhost" style configurations
+	      for web servers
+	<item>generate web server configuration files automatically
+	<item>include maintainer-specified directives in autogenerated 
+	      configurations files
+	<item>alternatively generate web server configuration by using 
+	      variable substitution into maintainer-supplied templates
+	<item>NOTYET: integrated support for database applications 
+	      via dbconfig-common (dbc needs manydb support)
+	<item>import configs from packages previously managing databases 
+	      on their own
+	<item>prompt users with a set of normalized, pre-translated questions
+	<item>NOTYET: handle failures gracefully, with an option to retry.
+	<item>work for package maintainers with little effort on their part
+	<item>do all the hard work automatically
+	<item>work for local admins with little effort on their part
+	<item>comply with an agreed upon set of standards for behaviour
+	<item>do absolutely nothing if it is the whim of the local admin
+	<item>perform all operations from within the standard flow of 
+	      debian package maintenance (no additional skill is required
+	      of the local admin)
+	</list>
+
+<chapt id="develguide">How To Use webapps-common For Web Applications
+	<p>
+	<strong>BIG DISCLAIMER</strong>: this is a work in progress.  standard
+	it-breaks-you-keep-the-pieces disclaimer here.
+	<p>
+	Okay, so this all sounds great... but how do I use it in my
+	package, you ask?  This may depend on your particular needs,
+	but chances are you can do so by simply putting some simple
+	commands and variables in your maintainer scripts, and
+	of course updating your dependencies.
+	<sect id="installtype">Choose your method of configuration
+		<p>
+		The first step depends largely on the application
+		you are packaging, and how complicated the webserver
+		configuration file needs to be.  Because of this, there
+		are currently three different methods you can use for
+		installing via webapps-common:
+		<taglist>
+		<tag>simple
+		<item>the easiest method to use, but also the least
+		      flexible.  it works by automatically generating web
+		      server configuration files based on the input from
+		      the admin during installation.  if your application
+		      requires additional specific directives (setting
+		      php flags, for example) this method will not work
+		      for you.
+		<tag>inline
+		<item>works by injecting the contents of a file you
+		      provide into the "middle" of the generated
+		      configuration files.  If your package only needs
+		      a few extra configuration options set, this may
+		      be the option for you.
+		<tag>template
+		<item>works by copying a file you provide, and performing
+		      some simple variable-substitution before putting
+		      the file in place.  This is probably the most
+		      powerful of the three options, but also the most
+		      complex, as then the burden is put on you to
+		      make sure the file in question will support the
+		      various combinations of ways in which someone would
+		      install your package (subdir, vhost, etc). TODO:
+		      more documentation on this.
+		</taglist>
+	<sect id="simple">The simplest example - "simple"
+		<p>
+		In the simplest case, you can activate webapps-common by
+		adding two lines in each of your maintainer scripts that
+		source the appropriate webapps-common shell script library,
+		and call the <var>wc_go</var> function.  For example, the
+		config script should look like:
+		<example>
+		. /usr/share/debconf/confmodule
+		. /usr/share/webapps-common/dpkg/config
+		wc_go packagename $@
+		</example>
+		<p>
+		TODO: do we really need to do this in the preinst?  If we
+		did, you'd have to pre-depend, which we don't want to do.
+		we had the same problem in dbconfig-common and it was solved
+		by removing the need for a preinst hook altogether.
+		was a problem in dbconfig-common 
+
+
+		
+		
 <chapt id="related">
 	Related Documents
 	<p>