Software: Apache/2.0.54 (Fedora). PHP/5.0.4 

uname -a: Linux mina-info.me 2.6.17-1.2142_FC4smp #1 SMP Tue Jul 11 22:57:02 EDT 2006 i686 

uid=48(apache) gid=48(apache) groups=48(apache)
context=system_u:system_r:httpd_sys_script_t 

Safe-mode: OFF (not secure)

/usr/share/4Suite/Demos/Loritaire/   drwxr-xr-x
Free 3.41 GB of 27.03 GB (12.6%)
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     quicktour.doc (13.32 KB)      -rw-r--r--

<?xml version="1.0"?>
<?xml-stylesheet href="docbook_html1.xslt" type="text/xsl"?>
<article
  xmlns="http://docbook.org/docbook/xml/4.0/namespace"
  xmlns:common="http://namespaces.fourthought.com/doc-common"
  xmlns:dc= "http://purl.org/dc/elements/1.1/"
  version="1.0"
>

  <articleinfo>
    <title>Loritaire Tour of Technology</title>

     <author>
       <firstname>Mike</firstname>
       <surname>Olson</surname>
       <affiliation>
         <orgname><ulink url="http://Fourthought.com">Fourthought, Inc.</ulink></orgname>
         <address><email>mike.olson@fourthought.com</email></address>
       </affiliation>
     </author>
     <revhistory>
       <revision>
         <revnumber>1.0</revnumber>
         <date>2000-12-11</date>
         <authorinitials>MO</authorinitials>
         <revremark>Initial release</revremark>
       </revision>
     </revhistory>

     <legalnotice>
       <para>This document can be freely translated and distributed. It's released under the <ulink url="http://www.linuxdoc.org/manifesto.html">LDP License</ulink>.</para>
     </legalnotice>

     <keywordset>
       <keyword>4Suite</keyword>
       <keyword>readme</keyword>
       <keyword>help</keyword>
       <keyword>demo</keyword>
       <keyword>Loritaire</keyword>
     </keywordset>

    <abstract>
      <para>Tour of Technology for 4Suite Server demonstration program Loritaire
      </para>
    </abstract>

  </articleinfo>

  <sect1>
    <title>Description</title>
    <para>Lorataire is a game of solitaire that was intriduced to me by Lori Ogbuji.  I'm not sure what the real name of this game is, so I made it up.  For rules of the game see the <ulink url='instructions.doc?xslt=docbook_html1.xslt'>instructions</ulink></para>
  </sect1>
  <sect1>
    <title>Introduction</title>
    <para>The demonstation application Loritaire uses 4Suite as the engine to drive the game play.  To perform this tour, there is a non-randomized game setup <ulink url='games/tour.xml?xslt=../play.xslt'>here</ulink>.  This document will walk you through a couple of turns in the non-randomized game and explain what is going on behind the scenes along the way.  It is best if you open up the non-randomized game in another browser window.</para>
    <sect2>
      <title>Files</title>
      <para>All of the game play for loritaire is written in XSLT.  There are three main files</para>
      <glosslist>
        <glossentry>
          <glossterm><ulink url='../common/cards.xslt?xslt=../loritaire/decorated-xml.xslt'>/common/cards.xslt</ulink></glossterm>
          <glossdef>Common templates used in all card games.  The main routines in here are for dealing multiple decks of cards</glossdef>
        </glossentry>
        <glossentry>
          <glossterm><ulink url='start.xslt?xslt=decorated-xml.xslt'>/loritaire/start.xslt</ulink></glossterm>
          <glossdef>Template used to create a new game.  It suffles and deals a game of Loritaire.</glossdef>
        </glossentry>
        <glossentry>
          <glossterm><ulink url='play.xslt?xslt=decorated-xml.xslt'>/loritaire/play.xslt</ulink></glossterm>
          <glossdef>Templates to control the flow of the game and display the board.</glossdef>
        </glossentry>
      </glosslist>
    </sect2>
    <sect2>
      <title>Game State</title>
      <para>The state of a game is stored in an XML file.  The example used in this tour is <ulink url='games/tour.xml?xslt=../decorated-xml.xslt'>here</ulink>.  The XML document is broken into 4 parts.  The first, is a list of eight target tags.  The children of these tags will be card elements as the cards are moved from the piles to the target stacks.  The second part of the XMl document are the piles.  Again, each of these tags will contain card elements that represent the cards in each pile.  The third section of the file is the stack element.  It also contains the child elements that are card elements that represent the cards in the playing stack.  Lastly, the cur-hand tag tag contains the value that represents the current pile that is being played.  If this value is negative one, then there is no pile being played.
      </para>
    </sect2>
  </sect1>
  <sect1>
    <title>Creating a game</title>
    <sect2>
      <title>New Game Document</title>
       <para>When a new game is started, a new document is created to represent the game.  All games are stored in the games subdirectory and given a UUID as their file name.  When a game is created, the template named shuffle-cards in /common/cards.xslt is used to shuffle  decks of cards.  These cards are stored in a variable called deck</para>
       <screen>
    &lt;xsl:variable name='deck'>
      &lt;xsl:call-template name='shuffle-cards'>
        &lt;xsl:with-param name='num-decks' select='2'/>
      &lt;/xsl:call-template>
    &lt;/xsl:variable>
        </screen>
        <para>
        The template mode "deal" is then used to deal the the deck of cards.  These templates implement the dealing rules described in the <ulink url='instructions.doc?xslt=docbook_html1.xslt'>instructions</ulink>.  In essence the templates are a small state machine that puts the cards into the proper piles and the playing stack.
        </para>
        <para>
        Once the cards have been dealt, the extension element fcore:create-document is used to create a new document in the repository.  Then the extension element fhttp:response-uri is invoked.  This element is used to tell the server that the results of this stylesheet should send a HTTP 302 (Temporary Redirect) to a specific URL.  It is very useful when you want a set of templates to manipulate some data, then use a common set of templates for viewing the data.
        </para>
        <screen>
    &lt;fhttp:response-uri uri="games/{$new-id}?xslt=../play.xslt&amp;user-name={$user-name}"/>
        </screen>
        <para>
        The last extension, fcore:mark-temporary, is used to mark the new document as temporary which is explained in the next section.
        </para>
    </sect2>
    <sect2>
      <title>Temporary Files</title>
      <para>When a new game is created, a new document is added to the repository.  Because, there is no way of knowing when the game is over, ie a person could just stop playing, we need a way of cleaning up the stale game documents.  To do this, we mark each of the game documents as temporary and give them a 900 second time to live.  We also update this time to live every time that the document is redisplayed.
      </para>
      <screen>
        &lt;fhttp:response-uri uri="games/{$new-id}?xslt=../play.xslt&amp;user-name={$user-name}"/>
      </screen>
      <para>
        With the document marked as temporary, you need to have the temporary file reaper enabled in the server.  To do this, you must define the TemporaryReapInterval property in the Core resource of your server config file.
      </para>
      <screen>
    &lt;TemporaryReapInterval>300&lt;/TemporaryReapInterval>
      </screen>
    </sect2>
    <sect2>
      <title>Initialization Complete</title>
      <para>With the board initialized and stored as an XML doc in the repo we can move onto displaying the initial board.</para>
    </sect2>
  </sect1>
  <sect1>
    <title>Displaying the board.</title>
    <para>
      Displaying the board is done with the file <ulink url='play.xslt?xslt=decorated-xml.xslt'>play.xslt</ulink>.  When first called with an initialized board, we just display the board.  The template named <emphasis>display-board</emphasis> is used to render the board.  These templates, render the HTML version of the board based on the the state of the XML document.
    </para>
  </sect1>
  <sect1>
    <title>Making a move.</title>
    <para>There are three possible moves to be made in loritaire, play the next card from the playing stack, move a card to a upward counting stack, or move a card to a down ward counting stack.</para>
    <sect2>
      <title>Next Card Action</title>
      <para>When a game is started, or there are no more plays to an upward are downward counting target, then you must play the next card from the playing stack.  To do this, you press the card backs in the middle of the screen.  This image is an href to the game document with the following query params
      </para>
      <glosslist>
        <glossentry>
          <glossterm>xslt</glossterm>
          <glossdef>Specifies the XSLT to render against the game document, in this case play.xslt</glossdef>
        </glossentry>
        <glossentry>
          <glossterm>do</glossterm>
          <glossdef>Specifies to the stylesheet which action the user is trying to perform.  In this case "next"</glossdef>
        </glossentry>
        <glossentry>
          <glossterm>user-name</glossterm>
          <glossdef>The name of the user that is playing the game.</glossdef>
        </glossentry>
      </glosslist>
      <para>
        All three of these parameters are passed into the stylesheet as external parameters.  The stylesheet can then use them to effect processing.  In the case of play.xslt, it performs an xsl:choose based on the value of the do paramater.  In the case of this liknk, the do parameter is next.
      </para>
      <screen>
    &lt;xsl:choose>
      &lt;xsl:when test='$do = "NEXT"'>
        &lt;!--
             Remove from the stack
             Add to the pile
             Update the cur_hand
             -->
        &lt;fhttp:response-uri uri="{$fres:uri-path}?xslt=../play.xslt&amp;user-name={$user-name}"/>

        &lt;fcore:x-update>
          &lt;xupdate:modifications
            version="1.0"
            xmlns:xupdate="http://www.xmldb.org/xupdate"
            >
            &lt;xupdate:remove select="/loritaire/cards/stack/Card[1]"/>
            &lt;xupdate:append select="/loritaire/cards/pile[{cards/stack/Card[1]/@value-int}]" child="last()">
              &lt;xsl:copy-of select='cards/stack/Card[1]'/>
            &lt;/xupdate:append>
            &lt;xupdate:update select="/loritaire/cur-hand">&lt;xsl:value-of select='cards/stack/Card[1]/@value-int'/>&lt;/xupdate:update>
          &lt;/xupdate:modifications>
        &lt;/fcore:x-update>

        &lt;fcore:mark-temporary uri="{$fres:uri-path}" time-to-live="900"/>

      &lt;/xsl:when>
      </screen>
      <para>
        When the the value of do is next, then we use XUpdate to modify the state of the game document.  We perform and XUpdate that removes the top card from the dtack, then appends it the the end of the pile that coresponds to its value.
      </para>
    </sect2>
    <sect2>
      <title>Making the move</title>
      <para>On the tour game, press the card back to start the game.  After you press the card, the board is redisplayed.  Below the playing stack the twelveth pile of cards is layed out.  You can determine this because there is an X where the twelveth pile should be.  Also, the last card displayed in the line of cards is a queen which lets you know that the twelveth pile is being played.</para>
    </sect2>
    <sect2>
      <title>Moving cards to the targets</title>
      <para>When the cards are moved to the target piles, the same process as when they are moved from the playing stack.  The only difference is that we have to verify that the card can be used.  We verify it by comparing it to the top card on the destination target pile.  If the card cannot be moved, then we call the template <emphasis>error-messahe</emphasis>.  This displays an error message to the user explaining what they did wrong.
      </para>
    </sect2>
    <sect2>
      <title>Making the move</title>
      <para>
        After the game is started, there are two immediate moves available on the board.  The first, is to move the Ace of Diamonds that is on the first pile to the upward counting target stack.  This is done by pressing the up arrow button to the right of the card.  After the button is pressed, the board is redisplayed with the ace in its proper place on the second target stack, and the first pile now has a ten of clubs showing.
      </para>
      <para>Now that the Ace of Diamonds is on the target pile, there is another move available to use, the Two of Diamonds on the tenth pile can be move to the target pile by pressing the up arrow to its right.  The board is redisplayed and a Jack of Hearts is uncovered when the Two of Diamonds is moved
      </para>
      <para>
        This is the end of counting up diamonds for now.  There is still a move available to us, the King of Hearts can be put on the counting down target.  You do this by pressing the down arrow to the cards right.  you can then follow this move up by moveing the Queen and Jack of Hearts
      </para>
      <para>
        Moving the King of Hearts uncovered the Three of Diamonds.  This can be moved to the upward counting target pile.  Aftere this move, there are no more moved available with the current playing card.  You need to uncover the next playing card by pressing the card pile in the center.
      </para>
      <para>Pressing the card back invoked the NEXT operation.  This, put the twelveth pile back where it was, then drew the top card from playing stack.  It was the Ten of Diamond (anyone know how I knew what card it was?).  Then, it put the Ten of Diamonds on the back of the tenth pile and displayed that pile for us to play off of.  There is on move available to us on the current board.  After that I leave the rest of the game to you.
      </para>
      <para>BTW, you should be able to move 77 cards to the target pile before you run out of playing cards with the tour.xml document</para>         
    </sect2>
  </sect1>
</article>