grim/guifications3

a crapton of documentation updates, mostly graphs but more comming
org.guifications.gf3
2009-08-30, Gary Kramlich
5937f0371791
Parents ad49254bc179
Children f46a1ec661c1
a crapton of documentation updates, mostly graphs but more comming
8 files changed, 419 insertions(+), 29 deletions(-)
  • +40 -3
    docs/specification/Makefile
  • +43 -0
    docs/specification/graphs/abstract_growl.digraph
  • +24 -0
    docs/specification/graphs/abstract_libnotify.digraph
  • +72 -0
    docs/specification/graphs/gf3_complex_abstract.digraph
  • +16 -0
    docs/specification/sheets/common.xsl
  • +191 -0
    docs/specification/sheets/digraph.xsl
  • +30 -0
    docs/specification/xml/about.xml
  • +3 -26
    docs/specification/xml/gf_spec.xml
    • --- a/docs/specification/Makefile Sun Aug 30 14:16:35 2009 -0500
    +++ b/docs/specification/Makefile Sun Aug 30 14:20:08 2009 -0500
    @@ -1,21 +1,58 @@
    TRANSFORM=xsltproc
    TRANSFORM_OPTS=--nonet --xinclude
    OUTPUT=html/
    +OUTPUT_GRAPHS=$(OUTPUT)/graphs
    BOOK=xml/gf_spec.xml
    SHEETS=\
    + sheets/common.xsl \
    + sheets/digraph.xsl \
    sheets/gf_spec.xsl
    BOOK_SOURCES=\
    + xml/about.xml \
    xml/gf_spec.xml \
    xml/communication.xml
    -all: xml/xml.stamp $(SHEETS) $(BOOK_SOURCES)
    +DIGRAPHS=\
    + graphs/abstract.digraph \
    + graphs/growl.digraph \
    + graphs/libnotify.digraph
    +
    +GRAPHS=$(DIGRAPHS:%.digraph=%.png)
    +
    +###############################################################################
    +# Basic Rules
    +###############################################################################
    +all: xml/xml.stamp $(SHEETS) $(BOOK_SOURCES) $(GRAPHS)
    clean:
    - rm -rf $(OUTPUT) xml/xml.stamp dir.stamp $(BOOK_BUILT_SOURCES)
    + rm -rf $(OUTPUT) xml/xml.stamp dir.stamp graphs/graphs.stamp
    +
    +###############################################################################
    +# Graph Rules
    +###############################################################################
    +.SUFFIXES: .digraph .png .dot
    +
    +.dot.png: dir.stamp
    + dot -Tpng -o $(OUTPUT)$@ $<
    + rm -f $<
    -xml/xml.stamp: $(BOOK_SOURCES) $(BOOK_BUILT_SOURCES) sheets/gf_spec.xsl
    +.digraph.dot:
    + $(TRANSFORM) $(TRANSFORM_OPTS) -o $@ sheets/digraph.xsl $<
    +
    +$(GRAPHS): dir.stamp $(DIGRAPHS) $(SHEETS)
    +
    +dir.stamp: $(OUTPUT_GRAPHS)
    + touch dir.stamp
    +
    +$(OUTPUT_GRAPHS):
    + mkdir -p $(OUTPUT_GRAPHS)
    +
    +###############################################################################
    +# Book Rules
    +###############################################################################
    +xml/xml.stamp: $(BOOK_SOURCES) sheets/gf_spec.xsl
    $(TRANSFORM) $(TRANSFORM_OPTS) -o $(OUTPUT) sheets/gf_spec.xsl $(BOOK)
    touch xml/xml.stamp
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/docs/specification/graphs/abstract_growl.digraph Sun Aug 30 14:20:08 2009 -0500
    @@ -0,0 +1,43 @@
    +<?xml version="1.0" encoding="utf-8"?>
    +<digraph>
    + <objects color="powderblue" shape="box" style="filled,rounded">
    + <object name="d_workstation" label="Workstation\ngrowl"/>
    + <object name="d_server" label="Server\ngrowl"/>
    + </objects>
    + <objects color="palegreen" shape="note" style="filled">
    + <object name="a_browser" label="Web Browser"/>
    + <object name="a_chat" label="Chat"/>
    + <object name="a_email" label="E-Mail"/>
    + <object name="a_multimedia" label="Multimedia"/>
    +
    + <object name="a_system_logger" label="System Logger"/>
    + </objects>
    + <objects color="lightyellow" shape="component" style="filled">
    + <object name="n_popup" label="Graphical Notification"/>
    + <object name="n_sms" label="SMS"/>
    + <object name="n_tts" label="Text To Speech"/>
    + </objects>
    + <relations>
    + <!-- device relations -->
    + <relation start="d_workstation" end="d_server"/>
    + <relation start="d_server" end="d_workstation"/>
    +
    + <!-- server applications -->
    + <relation start="a_system_logger" end="d_server"/>
    +
    + <!-- workstation applications -->
    + <relation start="a_browser" end="d_workstation"/>
    + <relation start="a_chat" end="d_workstation"/>
    + <relation start="a_email" end="d_workstation"/>
    + <relation start="a_multimedia" end="d_workstation"/>
    +
    + <!-- server notifications -->
    + <relation start="d_server" end="n_sms"/>
    +
    + <!-- workstation notifications -->
    + <relation start="d_workstation" end="n_popup"/>
    + <relation start="d_workstation" end="n_sms"/>
    + <relation start="d_workstation" end="n_tts"/>
    + </relations>
    +</digraph>
    +
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/docs/specification/graphs/abstract_libnotify.digraph Sun Aug 30 14:20:08 2009 -0500
    @@ -0,0 +1,24 @@
    +<?xml version="1.0" encoding="utf-8"?>
    +<digraph>
    + <objects color="powderblue" shape="box" style="filled,rounded">
    + <object name="d_workstation" label="Workstation\nnotification-daemon"/>
    + </objects>
    + <objects color="palegreen" shape="note" style="filled">
    + <object name="a_browser" label="Web Browser"/>
    + <object name="a_chat" label="Chat"/>
    + <object name="a_email" label="E-Mail"/>
    + <object name="a_multimedia" label="Multimedia"/>
    + </objects>
    + <objects color="lightyellow" shape="component" style="filled">
    + <object name="n_popup" label="Graphical Notification"/>
    + </objects>
    + <relations>
    + <relation start="a_browser" end="d_workstation"/>
    + <relation start="a_chat" end="d_workstation"/>
    + <relation start="a_email" end="d_workstation"/>
    + <relation start="a_multimedia" end="d_workstation"/>
    +
    + <relation start="d_workstation" end="n_popup"/>
    + </relations>
    +</digraph>
    +
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/docs/specification/graphs/gf3_complex_abstract.digraph Sun Aug 30 14:20:08 2009 -0500
    @@ -0,0 +1,72 @@
    +<?xml version="1.0" encoding="utf-8"?>
    +<digraph>
    + <!-- devices -->
    + <objects color="powderblue" shape="box" style="filled,rounded">
    + <object name="d_cell_phone" label="Cell Phone" color="lightpink"/>
    + <object name="d_laptop" label="Laptop"/>
    + <object name="d_server" label="Server"/>
    + <object name="d_workstation" label="Workstation"/>
    + </objects>
    +
    + <!-- applications -->
    + <objects color="palegreen" shape="note" style="filled">
    + <object name="a_laptop_battery_monitor" label="Battery Monitor"/>
    + <object name="a_laptop_browser" label="Web Browser"/>
    + <object name="a_laptop_chat" label="Chat"/>
    +
    + <object name="a_workstation_browser" label="Web Browser"/>
    + <object name="a_workstation_chat" label="Chat"/>
    + <object name="a_workstation_email" label="E-Mail"/>
    +
    + <object name="a_server_file_monitor" label="File Monitor"/>
    + <object name="a_server_ids" label="IDS"/>
    + <object name="a_server_syslog" label="System Logger"/>
    + </objects>
    +
    + <!-- notifiers -->
    + <objects color="lightyellow" shape="component" style="filled">
    + <object name="n_email" label="E-Mail"/>
    + <object name="n_popup" label="Graphical Notification"/>
    + <object name="n_sms" label="SMS"/>
    + </objects>
    +
    + <relations>
    + <!-- device relations -->
    + <relation start="d_laptop" end="d_server"/>
    + <relation start="d_laptop" end="d_workstation"/>
    +
    + <relation start="d_server" end="d_laptop"/>
    + <relation start="d_server" end="d_workstation"/>
    +
    + <relation start="d_workstation" end="d_laptop"/>
    + <relation start="d_workstation" end="d_server"/>
    +
    + <!-- application relations -->
    + <relation start="a_workstation_browser" end="d_workstation"/>
    + <relation start="a_workstation_chat" end="d_workstation"/>
    + <relation start="a_workstation_email" end="d_workstation"/>
    +
    + <relation start="a_laptop_battery_monitor" end="d_laptop"/>
    + <relation start="a_laptop_browser" end="d_laptop"/>
    + <relation start="a_laptop_chat" end="d_laptop"/>
    +
    + <relation start="a_server_ids" end="d_server"/>
    + <relation start="a_server_syslog" end="d_server"/>
    + <relation start="a_server_file_monitor" end="d_server"/>
    +
    + <!-- notifier relations -->
    + <relation start="d_workstation" end="n_email"/>
    + <relation start="d_workstation" end="n_popup"/>
    + <relation start="d_workstation" end="n_sms"/>
    +
    + <relation start="d_laptop" end="n_email"/>
    + <relation start="d_laptop" end="n_popup"/>
    +
    + <relation start="d_server" end="n_email"/>
    + <relation start="d_server" end="n_sms"/>
    +
    + <!-- notifier device relations -->
    + <relation start="n_sms" end="d_cell_phone"/>
    + </relations>
    +</digraph>
    +
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/docs/specification/sheets/common.xsl Sun Aug 30 14:20:08 2009 -0500
    @@ -0,0 +1,16 @@
    +<?xml version="1.0" encoding="utf-8"?>
    +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    + <xsl:output method="text"/>
    +
    + <xsl:strip-space elements="*"/>
    +
    + <!-- variables -->
    + <xsl:variable name="newline" select="'&#10;'"/>
    + <xsl:variable name="tab" select="'&#9;'"/>
    +
    + <xsl:variable name="newline-tab">
    + <xsl:value-of select="$newline"/>
    + <xsl:value-of select="$tab"/>
    + </xsl:variable>
    +
    +</xsl:stylesheet>
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/docs/specification/sheets/digraph.xsl Sun Aug 30 14:20:08 2009 -0500
    @@ -0,0 +1,191 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<xsl:stylesheet version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    + <xsl:import href="common.xsl"/>
    +
    + <!-- node attribute template -->
    + <xsl:template name="node_attribute">
    + <xsl:param name="key"/>
    + <xsl:param name="value"/>
    +
    + <xsl:text> </xsl:text>
    + <xsl:value-of select="$key"/>
    + <xsl:text>="</xsl:text>
    + <xsl:value-of select="$value"/>
    + <xsl:text>"</xsl:text>
    + </xsl:template>
    +
    + <!-- color template -->
    + <xsl:template name="color">
    + <xsl:param name="color"/>
    +
    + <xsl:call-template name="node_attribute">
    + <xsl:with-param name="key">fillcolor</xsl:with-param>
    + <xsl:with-param name="value" select="$color"/>
    + </xsl:call-template>
    + </xsl:template>
    +
    + <!-- shape template -->
    + <xsl:template name="shape">
    + <xsl:param name="shape"/>
    +
    + <xsl:call-template name="node_attribute">
    + <xsl:with-param name="key">shape</xsl:with-param>
    + <xsl:with-param name="value" select="$shape"/>
    + </xsl:call-template>
    + </xsl:template>
    +
    + <!-- style template -->
    + <xsl:template name="style">
    + <xsl:param name="style"/>
    +
    + <xsl:call-template name="node_attribute">
    + <xsl:with-param name="key">style</xsl:with-param>
    + <xsl:with-param name="value" select="$style"/>
    + </xsl:call-template>
    + </xsl:template>
    +
    + <!-- object template -->
    + <xsl:template name="object">
    + <xsl:value-of select="@name"/>
    +
    + <xsl:text>[</xsl:text>
    +
    + <!-- check for label -->
    + <xsl:if test="@label">
    + <xsl:call-template name="node_attribute">
    + <xsl:with-param name="key">label</xsl:with-param>
    + <xsl:with-param name="value" select="@label"/>
    + </xsl:call-template>
    + </xsl:if>
    +
    + <!-- handle the color attribute -->
    + <xsl:if test="@color">
    + <xsl:call-template name="color">
    + <xsl:with-param name="color" select="@color"/>
    + </xsl:call-template>
    + </xsl:if>
    +
    + <!-- handle the shape attribute -->
    + <xsl:if test="@shape">
    + <xsl:call-template name="shape">
    + <xsl:with-param name="shape" select="@shape"/>
    + </xsl:call-template>
    + </xsl:if>
    +
    + <!-- handle the style attribute -->
    + <xsl:if test="@style">
    + <xsl:call-template name="style">
    + <xsl:with-param name="style" select="@style"/>
    + </xsl:call-template>
    + </xsl:if>
    +
    + <xsl:text>];</xsl:text>
    + <xsl:value-of select="$newline-tab"/>
    + </xsl:template>
    +
    + <!-- relation template -->
    + <xsl:template name="relation">
    + <xsl:value-of select="@start"/>
    +
    + <xsl:text> -&gt; </xsl:text>
    +
    + <xsl:value-of select="@end"/>
    +
    + <xsl:if test="@label">
    + <xsl:text>[label="</xsl:text>
    + <xsl:value-of select="@label"/>
    + <xsl:text>"]</xsl:text>
    + </xsl:if>
    +
    + <xsl:text>;</xsl:text>
    +
    + <xsl:value-of select="$newline-tab"/>
    + </xsl:template>
    +
    + <!-- objects template, this allows us to use multiple objects tags -->
    + <xsl:template name="objects">
    + <!-- set our global node settings -->
    + <xsl:text>node[fontname="sans", fontsize="9", style="filled"</xsl:text>
    +
    + <!-- handle the color attribute -->
    + <xsl:if test="@color">
    + <xsl:call-template name="color">
    + <xsl:with-param name="color" select="@color"/>
    + </xsl:call-template>
    + </xsl:if>
    +
    + <!-- handle the shape attribute -->
    + <xsl:if test="@shape">
    + <xsl:call-template name="shape">
    + <xsl:with-param name="shape" select="@shape"/>
    + </xsl:call-template>
    + </xsl:if>
    +
    + <!-- handle the style attribute -->
    + <xsl:if test="@style">
    + <xsl:call-template name="style">
    + <xsl:with-param name="style" select="@style"/>
    + </xsl:call-template>
    + </xsl:if>
    +
    + <!-- close off our line -->
    + <xsl:text>];</xsl:text>
    + <xsl:value-of select="$newline"/>
    + <xsl:value-of select="$newline-tab"/>
    +
    + <xsl:for-each select="object">
    + <xsl:call-template name="object"/>
    + </xsl:for-each>
    + </xsl:template>
    +
    + <!-- main template -->
    + <xsl:template match="digraph">
    + <!-- start the diagram -->
    + <xsl:text>digraph {</xsl:text>
    + <xsl:value-of select="$newline-tab"/>
    +
    + <!-- output some basic stuff -->
    +
    + <!-- don't set a label if we don't have one -->
    + <xsl:if test="@name">
    + <xsl:text>label="</xsl:text>
    + <xsl:value-of select="@name"/>
    + <xsl:text>";</xsl:text>
    + <xsl:value-of select="$newline-tab"/>
    +
    + <xsl:text>labelloc="t";</xsl:text>
    + <xsl:value-of select="$newline-tab"/>
    + </xsl:if>
    +
    + <xsl:text>concentrate=true;</xsl:text>
    + <xsl:value-of select="$newline-tab"/>
    +
    + <xsl:text>splines=true;</xsl:text>
    + <xsl:value-of select="$newline-tab"/>
    +
    + <xsl:text>overlap=false;</xsl:text>
    + <xsl:value-of select="$newline-tab"/>
    +
    + <xsl:text>rankdir="tb";</xsl:text>
    + <xsl:value-of select="$newline"/>
    + <xsl:value-of select="$newline-tab"/>
    +
    + <!-- run through our objects -->
    + <xsl:for-each select="objects">
    + <xsl:call-template name="objects"/>
    + </xsl:for-each>
    +
    + <xsl:value-of select="$newline-tab"/>
    +
    + <!-- run through our relations -->
    + <xsl:for-each select="relations/relation">
    + <xsl:call-template name="relation"/>
    + </xsl:for-each>
    +
    + <!-- finish up -->
    + <xsl:value-of select="$newline"/>
    + <xsl:text>}</xsl:text>
    + <xsl:value-of select="$newline"/>
    + </xsl:template>
    +</xsl:stylesheet>
    +
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/docs/specification/xml/about.xml Sun Aug 30 14:20:08 2009 -0500
    @@ -0,0 +1,30 @@
    +<?xml version="1.0" encoding="utf-8"?>
    +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    +<chapter id="about">
    + <title>About</title>
    +
    + <para>
    + Guifications 3 is a framework for integrating a powerful notifiation
    + system into absolutely anything. The initial idea was started by
    + Gary Kramlich in 2003 when he first wrote the guifications plugin
    + for Pidgin (Gaim at the time). The idea has slowly been designed in
    + his head this document is meant to describe it on both a high and mid
    + level for everyone else.
    + </para>
    +
    + <para>
    + Theres been quite a bit of flux in exactly what the Guifications
    + framework is designed to do. Which is one of the many reasons why it
    + has taken so long to actually document it. The again I just don't
    + really enjoy documenting stuff, so choose which ever option suites you
    + best.
    + </para>
    +
    + <para>
    + This document should be treated as the living document it is. However,
    + as mentioned above, documenting isn't the first item on my todo list,
    + so there is a good change it will be slightly behind reality.
    + </para>
    +</chapter>
    +
    --- a/docs/specification/xml/gf_spec.xml Sun Aug 30 14:16:35 2009 -0500
    +++ b/docs/specification/xml/gf_spec.xml Sun Aug 30 14:20:08 2009 -0500
    @@ -6,30 +6,7 @@
    <title>Guifications Specification</title>
    </bookinfo>
    - <part id="gf3">
    - <title>About</title>
    - <partintro>
    - <para>
    - Guifications 3 is a framework for integrating a powerful
    - notification system into absolutely anything. The main driving
    - force behind Guifications 3 is the library gflib. This library
    - contains all of the basic objects for any an all Guifications
    - enabled application.
    - </para>
    -
    - <para>
    - The framework has been designed to be as neutral as possible for
    - not only desktops, but platforms as well. It provides the basic
    - behavior and leaves the implementation up for whatever platform
    - it may be used on. This is accomplished by abstraction for
    - inter-process communication, user interfaces, and preferences.
    - </para>
    - </partintro>
    - </part>
    -
    - <chapter>
    - <title>Overview</title>
    -
    - <xi:include href="communication.xml"/>
    - </chapter>
    + <xi:include href="about.xml"/>
    + <xi:include href="abstract.xml"/>
    + <xi:include href="communication.xml"/>
    </book>