[Webapps-common-discuss]
webapps-common/doc webapps-common.sgml, 1.2, 1.3
seanius at haydn.debian.org
seanius at haydn.debian.org
Wed Oct 19 17:58:33 UTC 2005
Update of /cvsroot/webapps-common/webapps-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv3623
Modified Files:
webapps-common.sgml
Log Message:
i think that will be it for today
Index: webapps-common.sgml
===================================================================
RCS file: /cvsroot/webapps-common/webapps-common/doc/webapps-common.sgml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- webapps-common.sgml 19 Oct 2005 14:53:19 -0000 1.2
+++ webapps-common.sgml 19 Oct 2005 17:58:28 -0000 1.3
@@ -52,10 +52,11 @@
of the local admin)
</list>
-<chapt id="develguide">How To Use webapps-common For Web Applications
+<chapt id="crashcourse">Quick HowTo for webapps-common and Web Applications
<p>
- <strong>BIG DISCLAIMER</strong>: this is a work in progress. standard
- it-breaks-you-keep-the-pieces disclaimer here.
+ <strong>BIG DISCLAIMER</strong>: this is a work in progress.
+ standard it-breaks-you-keep-the-pieces disclaimer here. I'm not
+ even promising i won't even change the API at this point.
<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,
@@ -101,28 +102,125 @@
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:
+ config script should contain:
<example>
. /usr/share/debconf/confmodule
. /usr/share/webapps-common/dpkg/config
- wc_go packagename $@
+ wc_go PACKAGE $@
</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
+ TODO: do we really need to do this in the preinst? I
+ don't think so. 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
+ <sect id="inline">Using "inline" configuration
+ <p>
+ If the application your packaging requires some
+ custom configuration, but not much, you might be
+ interested in trying the "inline" method. Using
+ this method is not much more complicated than the
+ "simple" case. The only difference is that you need
+ to specifically tell webapps-common to use this method,
+ and provide the file with the configuration directives.
+ <p>
+ The maintainer scripts should then look something like:
+ <example>
+ . /usr/share/debconf/confmodule
+ . /usr/share/webapps-common/dpkg/config
+ wc_apache_conf_style="inline"
+ wc_go PACKAGE $@
+ </example>
+ <p>
+ Additionally, you will need to provide the actual content
+ to be inlined. Let's imagine that you needed to have
+ the following configuration for your application:
+ <example>
+ #
+ # this is an example of an inline-included apache configuration.
+ # the following configuration will be included in a "Directory"
+ # block specific to this web application.
+ php_value include_path .
+ </example>
+ <p>
+ Then you would need to install a copy of this file as
+ <file>/usr/share/webapps-common/install/PACKAGE/httpd/apache_inline</file>,
+ which will automatically be detected and used by
+ webapps-common.
+ <sect id="template">Using "template" configuration
+ <p>
+ Perhaps your application requires a great deal of
+ configuration, or has some other strange requirements
+ such that the previous two methods will not work well
+ for you. In that case, using the "template" method may
+ be the best option. In this method, you supply a sample
+ file with the requisite server configuration options,
+ and then during the package configuration process certain
+ variable substitutions occur in the final output.
+ <p>
+ The maintainer script code looks about the same:
+ <example>
+ . /usr/share/debconf/confmodule
+ . /usr/share/webapps-common/dpkg/config
+ wc_apache_conf_style="template"
+ wc_go PACKAGE $@
+ </example>
+ <p>
+ And then you will need to provide the template configuration
+ file, which might look something like:
+ <example>
+ # this is a sample template-based configuration file for apache.
+ # this file will be included as-is, with the exception that
+ # certain substitutions will occur with the result
+ Alias _WC_WEBSITE_SUBDIRECTORY_ /usr/share/PACKAGE/www
+ </example>
+ <p>
+ <strong>TODO</strong>: this is actually a pretty crappy
+ example, because it could be done with the "simple"
+ method. Let's think of a better one.
+ <p>
+ This file would then be installed as part of your package in
+ <file>/usr/share/webapps-common/install/PACKAGE/httpd/apache_template</file>.
+ In this example, _WC_WEBSITE_SUBDIRECTORY_ would be
+ substituted with the value of the subdirectory from which
+ the application would be accessible on the webserver.
+ <p>
+ <strong>TODO</strong>: Generate a list of substitution
+ variables and talk about how this works with virtualhost
+ configs
+ <sect id="examples">Working Examples
+ <p>
+ If you would like to see working examples of packages
+ currently using webapps-common, grab the latest
+ webapps-common source from alioth, and look in the
+ examples subdirectory. This directory is a debian
+ source package that generates example packages implementing
+ each of the above installation methods.
+<chapt id="advanced">Advanced Techniques and Concepts
+ <p> TODO
+<chapt id="appendix">Appendix - Variables and Options
+ <p> TODO
-
-<chapt id="related">
- Related Documents
+<chapt id="related"> Related Documents
<p>
- <list>
- <item> Web application DRAFT document
- <item> Database application DRAFT document
- <item> PHP language DRAFT document
- </list>
+ The following documents have had a great deal of influence
+ on webapps-common:
+ <taglist>
+ <tag> <url id="http://webapps-common.alioth.debian.org/draft/html/" name="Web Applications DRAFT Policy Document">
+ <item>Discussion of the best practices for packaging web
+ applications in Debian. Fundamental design decisions
+ of webapps-common are made based on the consensus
+ reached in this document.
+ <tag> <url id="http://people.debian.org/~seanius/policy/dbapp-policy.html" name="Database Application DRAFT Policy Document">
+ <item>Similar to the above, but more strictly focusing on
+ aspects related to interacting with databases such
+ as MySQL or PostgreSQL.
+ <tag> <url id="http://webapps-common.alioth.debian.org/draft-php/html/" name="PHP Language DRAFT Policy Document">
+ <item>As PHP is quite popular programming language, it has
+ become important to have a mini-policy document
+ similar in spirit and scope to those of Perl and Python.
+ </taglist>
</book>
More information about the Webapps-common-discuss
mailing list