               [1]Billy-Bob Ming               * [3]Billy-Bob's Ming Server
             [2]Get The Good Stuff             * [4]Ming Server Incoming Data Handler
                                               * [5]Ming Server Python Data Type
               Ming Server Manual

    The Ming Server

    The Ming Server generates web pages statically or dynamically. Installed in cgi-bin, it creates those pages on demand from
    simple source files,  in response to  browser requests. Parsing  of different source  types and the  writing of pages  are
    separated, making it easy to extend The Ming Server to new data types or delivery methods.

    --------------------------------------------------------------------------------------------------------------------------

    DESCRIPTION

    In order to run ming.cgi, you will need:

      * The Ming Server installed as described in the INSTALL file; and
      * local/src/dir tree ready with its source files (see below).

    The site.html plate  (see data/site.html  in the  distribution) uses  HTML comment  and comment-end  tags in  column 0  to
    determine where data goes.  The tags "content", "title",  and "menu" are  automatically generated but need  not be in  the
    plate.

    The Ming Server will use any comment tags in the data and plate. So your normal comments must be indented one space or you
    will confuse our server. The "content" tag is used extensively as a default. Only "title" does not have an end tag and the
    formatting of its use as title element cannot be changed. This has to do with how browsers parse titles.

    COMMAND-LINE OPTIONS

    --debug
            Prints a verbose output for developer analysis. Note that ming.cgi normally exits with an exception in debug mode
            because ming.cgi normally ignores what does not matter to it, such as unused directories, etc.

    EXAMPLES

    Source Files

    The following are expected. Anything else is ignored. Examples are in the distribution's user/data dir tree.

      * key file
      * data files
      * site.html

    key file

    Key files take the following form, beginning with the first line of the file.

         file name (no extension)
         page title
         (optional descriptive line)
         (blank line)
         file name (no extension)
         page title
         (optional descriptive line)
         (blank line)
         .
         .
         .
         .
         file name (no extension)
         page title
         (optional descriptive line)
         (blank line)

    The ordering of the files in key determine the ordering of the menu and the file used as directory index is the first file
    in the key file. The page titles and the text following a menu link are defined here too.

    data file

    These have the type on the first line and all following lines are treated as data. The following types are available:

    html

    Data is treated as pure HTML. You  can break the data into pieces for  comment tags by separating the pieces with  comment
    tags. If no comment tags are found, all data is marked as "content"

    plain

    The entire data chunk is marked as "content" and dropped in as-is.

    pre

    The entire data chunk is marked as "content" and inserted between HTML pre-tags.

    3tml

    Data is first parsed for a simple markup language and then treated as html above. The language is line based, parsed  line
    by line and expects its markup in column 0. The markup is:

         !text - produces an h3 element with text
         @url some words - produces a link to url with "some words" as visible link
         | - by itself on a line, starts and stops blockquotes
         + - by itself on a line, starts and stops unordered lists (no nesting)
         \text - forces a line break before text
         [blank line] - a blank line forces a paragraph tag

    All types are exampled in the user/data tree.

    site.html

    The boiler plate for the site is simply an HTML file in  the top of the source tree. There is an example site.html in  the
    user/data tree.

    Setting PLATES  to 1  in Constants.py  makes The  Ming Server  use the  closest site.html  searching up  from the  current
    directory into its parents. Setting it to 0 make things run faster.

    DYNAMIC USAGE

    If you request this URL,

      http://your.dot.com/cgi-bin/ming.cgi?page=path/to/page

    The Ming Server will generate page at self.DATA/path/to/page

    CGI INSTALLATION

    The same python and data files used for static generation can be used to create a dynamically-generated web site. You will
    need a site with access to Python in the cgi-bin. And much more is possible by using the Python dynamically.

    These simple steps should get you up and running:

      * Put the executable "ming.cgi" in cgi-bin and give it world read-execute perms (unix 755)
      * Put the "TheMingServer" directory with the other Python scripts in cgi-bin, i.e.

          site/cgi-bin/TheMingServer

        and make sure they are world-readable (unix 644). They should already be -- but check.
      * Put the example "data" directory at the same level as cgi-bin and make all world-readable.
      * Take the refresh index.page, put your URL in there everywhere ours occurs, and install as your new "index.html" in
        your "htdocs" or "public_html" or whatever-it's-called directory.
      * Make sure everything in Constants.py is good for your server.

    WEB LOG

    The Ming Server can keep  its own log of  page requests. Logging is  done by the Logger  and controlled by PageMaker.  The
    following USER CONSTS should be set in Consts.py:

    LOGGING
            1 turns it on - 0 turns it off

    DIR
            Directory where "ming.cgi.tfc.log" lives. This must be placed where the CGI can write files. DIR = "." puts it in
            your cgi-bin.

    DEMO
            1 makes log public - 0 requires password

    PASSWD
            Used in the calls to view log

    You can then make the following calls to the log:

      http://your.dot.com/cgi-bin/ming.cgi?log=log

    Web log With Logger.DEMO set to 1. Web log is public

      http://your.dot.com/cgi-bin/ming.cgi?log=log&view=passwd

    Web log displayed privately. PASSWD set in Logger.

      http://your.dot.com/cgi-bin/ming.cgi?remove=passwd&item=title

    Web log is a Python dictionary and dict[title] will be removed.

    NOTES

    Add the param "debug=1" to the request and you will initialize Python's cgitb for debugging.

    The Ming Server can execute Python scripts and use the output of the script as the content of your page.
    See Python Data Type page on our site.

    The Ming Server can receive and record incoming data from forms which are then handled by your Python pages.
    See Incoming Form Data Handler page on our site.

    Architecture is object-based and simple. Data is parsed by parsers, built into pages by makers, written out by writers.  A
    new  parser  would  go  in  TheMingServer/parsers,  entered   in  the  parser  subpackage  __init__.py,  and  entered   in
    PageMaker.PARSERS.

                 [6]We Publish                           [8]You Publish                           [10]You Write
                 [7]We Publish                           [9]You Publish                           [11]You Write
                                                  [12]WHAT'S HOT ON BILLY-BOB?
          [13]Free Software Foundation                 [15]billy-bob ming                  [17]Creative Commons License
               [14]GPL'D Software                       [16]Our Founders                      [18]Copyrighted Works

References

   Visible links
   1. http://192.168.56.2/billybobming.html
   2. http://192.168.56.2/billybobming.html
   3. http://192.168.56.2/cgibin/ming.cgi?page=sites/ming/index
   4. http://192.168.56.2/cgibin/ming.cgi?page=sites/ming/01server/incoming
   5. http://192.168.56.2/cgibin/ming.cgi?page=sites/ming/01server/pytype
   6. http://billy-bob-ming.com/cgibin/ming.cgi?page=sites/billybob/breakfast
   7. http://billy-bob-ming.com/cgibin/ming.cgi?page=sites/billybob/breakfast
   8. http://billy-bob-ming.com/cgibin/ming.cgi?page=sites/ming/index
   9. http://billy-bob-ming.com/cgibin/ming.cgi?page=sites/ming/index
  10. http://billy-bob-ming.com/ghostwriter/
  11. http://billy-bob-ming.com/ghostwriter/
  12. http://192.168.56.2/cgibin/ming.cgi?page=open/logger/hits
  13. http://www.fsf.org/
  14. http://www.fsf.org/
  15. http://billy-bob-ming.com/billybobming.html
  16. http://billy-bob-ming.com/billybobming.html
  17. http://creativecommons.org/licenses/by-nc-nd/2.5/
  18. http://creativecommons.org/licenses/by-nc-nd/2.5/
