WikklyText A wikitext server and rendering library Fri, 18 Dec 2009 19:16:00 +0000 WikklyText 1.9.4 http://blogs.law.harvard.edu/tech/rss LatestNews LatestNews.html RecentChanges.

December 18, 2009


Version 1.9.3-TEST released. This is prerelease software, meant to let everyone have a preview of the new server frontend code. Please make a backup and test using that. See PreRelease for details and downloads.

October 11, 2009


Version 1.9.2-TEST released. This is prerelease software, meant to let everyone have a preview of the new server frontend code. Please make a backup and test using that. See PreRelease for details and downloads.

September 26, 2009


Version 1.9.1-TEST released. This is prerelease software, meant to let everyone have a preview of the new server frontend code. Please make a backup and test using that. See PreRelease for details and downloads.

September 18, 2009


Version 1.9.0-TEST goes live. Well, it turned out that moving to a new server did not eliminate the random lockups after all — they were just as bad as before. I came to the conclusion that the problem was in WikklyText itself, so I finally undertook a major refactoring of the wiki frontend I've been planning putting off for a long time. The test code is now live here and (crossing fingers) has not locked up once yet. If you run a wiki and are interested in checking out the new code prior to the 2.0 release, I encourage you to follow the MailingList as I'll be making further announcements there.

August 24, 2009


Wikklytext has moved to a new server. Hopefully this will eliminate the twice-daily reboots I was having to do with the old server. The new server seems snappier on first impression, keeping my fingers crossed ...

August 16, 2009


This release adds a new type of macro that takes a WSGI environment as an argument. You can also attach arbitrary WSGI applications to the wiki now.

September 28, 2008


WikklyText 1.5.0 is released. This is somewhat of a cleanup release with reorganization of the caching architecture, parsing cleanups and XHTML compliance fixes.


September 6, 2008


Added GettingPlugins page to collect plugins.

]]> e6c5037d6abccee273f2d202e43b3d5a5774222f Fri, 18 Dec 2009 19:16:00 +0000 PreRelease PreRelease.html
Please read before continuing
  • Make a backup copy and run a test using the backup before going live with this version. There have been significant changes that could leave you with a non-working wiki.
  • This release changes how the wiki is attached to the frontend server. You will need to redo your server side setup. Otherwise your wiki will not work. Please read ApacheIntegration carefully.


This is prerelease software and may leave you with a non-working wiki. If you want the stable version please see InstallPythonPackage instead.

Please report all problems to the MailingList.

Downloads
tar.gzWikklyText-1.9.3.tar.gz
zipWikklyText-1.9.3.zip
]]> 200c108c9f74edf0c156db2fa810bb71fd2bcf5c Fri, 18 Dec 2009 19:15:00 +0000 RecentChanges RecentChanges.html Version 1.9.3-TEST
For Testing
  1. This is a prerelease version for testing. Please backup your wiki and run the server on the backup copy to test it before going live.
  2. This release is not available on the regular download page nor via PyPI, in order to not affect stable installations. See PreRelease for downloads.
Changes
  • Removed wik makeboot command; no need for it anymore with new server frontend.
  • Added --frontend option to wik to select server type for standalone use.
  • Reworked camelword parsing again. Was not correctly recognizing camelwords when mixed with punctuation, like (CamelWord).
  • You can pass a context parameter to WikklyText_to_InnerHTML and WikklyText_to_XML now to specify your own WikContext. Reworked WikContext cloning to better support subclassing.

Version 1.9.2-TEST

For Testing
  1. This is a prerelease version for testing. Please backup your wiki and run the server on the backup copy to test it before going live.
  2. This release is not available on the regular download page nor via PyPI, in order to not affect stable installations. See PreRelease for downloads.
Changes
  • Search works again on wiki
  • Deleting items from wiki works again
  • Stop overwriting all css/* files on startup. Only overwrite wikklytext.css and wikklytext.js (they both warn against directly editing them). Leave others as-is so e.g. users can easy replace favicon, etc.
  • Added rawquoting of macro args. This is just like Python raw strings (i.e. r".."). The complete set of quoting styles available for macros args is now: bareword, '...', "...", '''...''', """...""", <quote>...</quote>, and rawquote variations r'...', r"...", r'''...''', r"""...""", <rquote>...</rquote>. Rawquoting with <rquote> is especially useful when cutting and pasting Python/C code into macro args like ...
    <<codebox "Some code" <rquote>
    ...
    ... Python/C code
    ...
    </rquote>>>


Version 1.9.1-TEST

For Testing
  1. This is a prerelease version for testing. Please backup your wiki and run the server on the backup copy to test it before going live.
  2. This release is not available on the regular download page nor via PyPI, in order to not affect stable installations. See PreRelease for downloads.
Major changes
  • Wiki frontend has been completely refactored into a pure WSGI application. This makes it significantly easier to attach the wiki to many types of servers.
  • Adapters included for CGI and mod_python (CherryPy no longer required).

Version 1.6.0

Upgrade notes ...
  1. This is a feature update release with the changes as shown below.
  2. You only need to install the Python library to get this upgrade. There is no need to update your Drupal plugin or update your Apache setup. (If you are using the standalone .exe then just download the new version(s).)
Major changes
  • Python 2.4 is now the minimum version for running the wiki. If you just use the rendering library, Python 2.3 is fine.
  • Stop sending Content-Type="application/xhtml+xml" - causes strange browser behavior. Use just text/html on all browsers.
  • Plugins can now attach arbitrary WSGI applications to wiki by exporting them via __wsgi_apps__
  • New WSGI macro type receives a WSGI-like environment (among other things, this lets macros access the wiki directly). These are exported via __wsgi_macros__.
  • Browsing to $SITE/api/plugins shows information about loaded plugins.
  • Ensure request data saved on a per-thread basis
  • Allow port numbers in parsed URLs

Version 1.5.0

Upgrade notes ...
  1. This is a major update with many underlying architectural changes and a few user visible changes.
  2. You only need to install the Python library to get this upgrade. There is no need to update your Drupal plugin or update your Apache setup. (If you are using the standalone .exe then just download the new version(s).)
Major changes
  • Caching is now done at the wikitext->XML layer, instead of wikitext->HTML. This has several benefits including:
    • Macros are now evaluated every time, instead of just the first time the wikitext is parsed (no more need for the -cache tag; you can safely remove it).
    • Auto-links to unknown CamelWords or links like [[My new word]] now work with caching turned on.
    • Bottom line: You can safely turn caching back on for all cases now.
  • API Change: Keyword parameter plugin_dir changed to plugin_dirs in several places to reflect the lower level semantics. Old keyword still accepted for now.
  • Can specify extra paths to look for plugins on wiki admin page. This is convenient when you want to have several wikis yet keep your plugins in a single location.
  • Fix macro parsing for nested calls like <<aaa<<bbb
  • Cleanups for XHTML conformance — now passes tests @ http://validator.w3.org/ in strict mode
  • Links (both [[..]] and [img[..]]) can no longer have inner markup. Allowing inner markup was occasionally useful but caused too many problems with TiddlyWiki compatibility. Although this is a markup change, it is compatible with TiddlyWiki so hopefully won't cause too many problems. Please double-check your links after updating.
  • Fixed CamelWord parsing so that abcDefGhi is not seen as abc[[DefGhi]]
  • rendercache entries now expire to keep cache from growing indefinitely (parameters set through wiki admin page)
  • Turn off browser caching of command responses
  • [[/my/path]] will now make a file:/// link if /my/path is a valid path
  • Rendering time limit now configurable on admin page. Fixed bug in time limit handling.
  • Speedups in rendering for all store types; text stores benefit the most from these changes.

Version 1.4.0

Upgrade notes ...
  1. This is a major feature release with the addition of the many features listed below.
  2. You only need to install the Python library to get this upgrade. There is no need to update your Drupal plugin or update your Apache setup. (If you are using the standalone .exe then just download the new version(s).)
User-visible changes
  • Now creates autolinks to unknown CamelWords and links, just like TiddlyWiki does. Turned off by default to avoid surprising existing users. You can enable this behavior from the admin page.
  • Metadata updates are now automatically applied. No longer have to shutdown wiki and run wik updatemeta from the command line.
  • Added user-defined log filters on admin page.
  • Added StyleSheet link on admin page for convenience.
  • Added button on admin page to clear rendercache.
  • Stricter parsing of CamelWords — now accepts alphabetical only.
  • Fixed cache handling in SiteTitle()/SiteSubtitle()
  • Tags nocache and norss changed to -cache and -rss.
  • Added <<div>> and <<span>> macros.
  • Fixed <nowiki> handling.

Internal changes
  • New plugin API make it easy to add user-defined macros. (see WritingPlugins)
  • API Changes
    • URL resolvers now return linktype as string ('internal', 'external', or 'newitem') instead of True/False to allow more types of links. (For backwards compatibility, True/False are still accepted.)
    • wikStore_tw_re can no longer be used directly. wikStore_tw has always been marked as the official interface; if you are using wikStore_tw_re just change to wikStore_tw, it has the same API.
  • var_get_* and var_set_* functions moved into WikContext. Old functions left in place for now to avoid breaking API, but marked as deprecated.
  • Added file locking to wikStore_tw
  • Updated wikStore_sqlite for multiprocess use.
  • Added locking to wikStore_files
  • More comprehensive time handling in wikStore_tw to account for many variations in TiddlyWiki formats.
  • Fixes for CherryPy 3.1-final

Version 1.3.0

Upgrade notes ...
  1. This is a major feature release with the addition of the GUI 'control center' application.
  2. You only need to install the Python library to get this upgrade. There is no need to update your Drupal plugin or update your Apache setup. (If you are using the standalone .exe then just download the new version(s).)
  • New GUI "control center" for managing wikis. It is particularly useful if you are running several local wikis and don't want to keep starting/stopping them by hand. This is now the default command if you simply run wik.exe or wikgui.exe.
  • SiteTitle and SiteSubtitle are now rendered correctly.
  • Fixed handling of embedded Python code (<?py) so that globals are visible.
  • Added CherryPy to auto dependencies.
  • Allow turning on/off metadb usage in wiki admin page (will enable/disable logging.)
  • Allow turning on/off caching in wiki admin page.
  • Added --no-respawn command-line option to prevent wiki from doing an auto-restart on exit. (Primarily for use by wik and wikgui.)
  • Create rss.xml when running "wik render"
  • RSS feed now validates with no warnings at http://feedvalidator.org/

Version 1.2.2

Upgrade notes ...
  1. This is a minor bugfix update. There is no need to update unless you need the fix (see below).
  2. You only need to install the Python library to get this upgrade. There is no need to update your Drupal plugin or update your Apache setup. (If you are using the standalone .exe then just download the new version.)
  • Updated to handle wikis created with TiddlyWiki 2.4.0. (Works will all versions of TiddlyWiki from 2.0-2.4)

Version 1.2.0


Upgrade notes ...
  1. This upgrade is highly recommended for all users. Version 1.1 had a showstopper bug in its XSS filter.
  2. You only need to install the Python library to get this upgrade. There is no need to update your Drupal plugin or update your Apache setup. (If you are using the standalone .exe then just download the new version.)
  3. You should run wik clean on your wiki(s) after this upgrade to clear the cache of any badly generated files from version 1.1.
Changes:
  • Added compatibility with CherryPy 3.1beta (version 3.0.x still supported).
  • Redirect requests for "PageName" to "PageName.html" (assuming "PageName" is a valid item).
  • XSS filter was too aggressive in filtering URLs based on server names, breaking wiki links when running locally. Thanks to Doug Gephardt for the report.
  • Eliminated potential information leak in server.
  • Allow uppercase letters in CSS classnames.
  • Log more information on failed logins.
  • Show CherryPy version on admin page.

Version 1.1.0


Upgrading ...
  1. You only need to install the Python library to get this upgrade. There is no need to update your Drupal plugin or update your Apache setup. (If you are using the standalone .exe then just download the new version.)
  2. A metadata update is needed after installing this upgrade. You will see instructions in your wiki on what to do.
Changes:
  • Added RSS (2.0) feed to wiki. Feed is formatted to allow autodiscovery so you don't need to do anything. You can exclude items from the RSS feed by tagging them with norss.
  • Wiki will now serve any files found in folder files/ under your wiki root folder. See ServingFiles for more information.
  • API Change wikStore.py: Moved tag_add(), tag_del() and tag_toggle() into WikklyItem.
  • Always place absolute URLs in generated HTML. This was added to allow page links in the RSS feed to point to the correct location.
  • Stop putting domain names in parens next to links when rendering in safe mode. This was causing some aesthetic issues; it may be reenabled in a future release.
  • Stop performing reverse DNS lookups when showing logs. Far too slow.
  • Serve robots.txt (no restrictions currently; was added to prevent errors when crawlers request it).
  • Added more log reporting links on admin page.
  • Watch for buggy browsers that request favicon.ico instead of favicon.png as specified in <HEAD>

Version 1.0.0


  • The major new feature is addition of wiki metatool "wik". With this tool, WikklyText now provides a full-blown wiki server. Using "wik", you can create, render, and serve editable multiuser wikis over HTTP. It is equally suitable for use as a WikiOnAStick as well as serving BehindApache

  • Hundreds of fixes, improvements, and stabilization for version 1.0

Version 0.99.50


  • Minimum requirement is now Python 2.3.5. Python 2.2 has a number of issues and setuptools does not support < 2.3.5 anyways.

  • New abstract storage layer (wikStore) that allows reading & writing wikitexts from Tiddlywikis, a flat set of text files, and SQLite databases.

  • No longer requires lxml package.

  • Rewrote twextract to use new storage layer.

  • Sources reorganized into a setuptools package with a standard setup.py.

  • Scripts installed to PYTHONDIR/Scripts (directly runnable, no more user-created wrappers needed).

  • wikkly2html.py now does a chdir() to sourcefile path so included files, etc. can always be found in a predictable location.

  • Some refactoring, renaming and other cleanups.

  • Version info now in version.py instead of wikkly_fmt.info



]]> cb6925368e7ad4fd88c6442050bf6cff97c851f6 Fri, 18 Dec 2009 19:12:00 +0000 Tags Tags.html <!--
    These are the tags generated by wikklytext.buildXML and recognized 
    by wikklytext.buildHTML. Macros are allowed to generate and 
    return any of these as well.

    Last synced with WikklyText sources on 2009-10-08
    
    -- CAUTION -------------------------------------------------------------
    Macro writers MUST ensure that no unfiltered user data is injected into
    the 'style' attribute of <MacroBlock> or <MacroInline> 
    (at least in Safe Mode). 

    This is the only attribute that is not sanity checked when generating
    HTML in Safe Mode.
    ------------------------------------------------------------------------

    General note: Only the <Text*> tags are allowed to have
    character content. ALL of the remaining tags (except for
    the self-closing tags) are containers.
    
    Overall structure:
       <WikklyContent>
          <ErrorsList>
          ..
          </ErrorsList>
          
          <Content>
          ..
          </Content>
-->    

<!-- Overall container -->
<WikklyContent>

<!-- Container for content -->
<Content>

<!-- Used to pass around lists of Elements. Ignore for 
     HTML output (output subelements instead).
-->
<ElementList>

<!-- 
    Links. Only the following subnodes are recognized.
-->
<Link>
  <!-- The object linked to, i.e. <a ..> LinkSource </a> -->
  <LinkSource>
  <!-- The URL, i.e. <a href="LinkDest"> ... </a> -->
  <LinkDest>
  
<!-- 
    Basic text styling, can be nested freely (although for example
    nesting <Bold> inside <Bold> makes no sense, it is allowed).
-->
<Bold>
<Italic>
<Strikethrough>
<Underline>
<Superscript>
<Subscript>

<!-- 
     Generic inline CSS styling.
     If 'style' is missing, uses default highlighting. 
     In 'Safe Mode', style is ignored to prevent HTML injection.
-->
<Highlight [style="CSS style string"]>

<!-- Numbered lists. 'level' is indent level. -->
<NumberedList>
  <NumberedListItem level="NR">

<!-- Unumbered lists. 'level' is indent level. -->
<UnnumberedList>
  <UnnumberedListItem level="NR">  

<!-- Headings. 'level' is heading level -->  
<Heading level="NR">

<!-- Do a block or line indent of contents -->
<BlockIndent>
<LineIndent>

<!-- A block of code -->   
<CodeBlock>

<!-- Inline code -->
<CodeInline>

<!-- 
    Create a named anchor. Uses the first <Text> node
    as the name 
-->
<CreateAnchor>

<!-- Images -->
<Image>
   <!-- Optional: URL to link to (when image is clicked) -->
   <ImageLink> 
   <!-- Source of image, i.e. for <img src=ImageFilename> -->
   <ImageFilename>
   <!-- Title for popup -->
   <ImageTitle>
   
<!-- Tables -->
<Table>
    <!-- Caption, must be first tag if present -->
    <TableCaption>
    <!-- Each row ... -->
    <TableRow>
        <!-- Each cell ... 
             In "Safe Mode", bgcolor is ignored to prevent HTML injection. -->
        <TableCell type="header|data" text-align="left|center|right"
                   [skip="1"] [colspan="NR"] [rowspan="NR"] [bgcolor="color"]>
      
<!-- Definition lists -->
<DefinitionList>
    <!-- Each list entry ... -->
    <DefinitionEntry>
        <!-- One Term & Def per entry.
             Both must be present (even if empty) and in order. -->            
        <DefinitionTerm>
        <DefinitionDef>
      
<!-- A block of content styled by the given CSS class -->        
<CSSBlock class="CLASSNAME">

<!-- Self-closing tags (no subnodes recognized) -->
<Separator />
<BlankLines count="NR" />
<LineBreak />
<DashChar />

<ErrorsList>
    <Error>
        <ErrorMessage>
        <ErrorLookingAt>
        <ErrorTrace>

<!-- 
  A MacroBlock is a DIV-like element with optional class, style, and id attributes.
  It is called "MacroBlock" because it is meant for use by macros to define 
  their own blocks when an existing tag won't do. 
-->
<MacroBlock [class="CLASSNAME"] [style="CSS style"] [id="ID"]>


<!--
  MacroInline is the same as MacroBlock, but is meant as a <span>
  element instead of a <div>.
-->
<MacroInline [class="CLASSNAME"] [style="CSS style"] [id="ID"]>

<!-- 
    As noted above, only <Text*> nodes are allowed to contain
    character data. There are several types of Text nodes depending
    on the type of content.
    
    Text nodes are not allowed to have any subnodes; only their
    character data is recognized.
-->

<!-- Normal text, HTML-special chars are escaped -->
<Text>

<!-- Like <Text>, but whitespace is preserved as well -->
<TextCode>

<!-- No escaping, written as raw chars 
     In "Safe Mode", these are ignored. -->
<TextHTML>

<!-- For URLs under LinkURL or ImageSource tags -->
<TextURL>

<!-- Like <Text> but no wikification of text is performed -->
<TextNoWiki>

<!-- For 2.x parser -- not yet implemented -->

<!-- A macro call -->
<MacroCall>
<!-- Subnodes will be either ... -->
<TextMacroArg>
<!-- 
   ... for args parsed directly from wikitext, but can
   be any other type of node for nodes that have already been evaluated. 
   (Note especially that another <MacroCall> can be one of the elements
   to denote an inner macro call.)

  The name of the macro to call is simply be the first element.text
-->

<!-- Embedded Python code -->
<PyCode>
   <TextPyCode> .. code here ...

]]> 9945e83c8ada43ad1169cfd85593a67b01c0d75b Thu, 08 Oct 2009 14:15:00 +0000 Apache+CGI+mod_rewrite+cgi-bin Apache+CGI+mod_rewrite+cgi-bin.html
Please read before continuing
  • These instructions are for WikklyText 1.9.x. If you are running an earlier version, see BehindApache instead.
  • If you are upgrading from WikklyText 1.6.x or earlier, you can delete the file wikboot.py in your wiki folder. It is no longer used.
This recipe covers a configuration commonly available on shared webhosts where you are allowed to run CGI scripts, but you are required to place them in a predetermined cgi-bin directory. The following locations are assumed — adjust as needed:
Wiki filesystem location
/var/www/wikis/mywiki
CGI script directory
/var/www/cgi-bin
Public URL
http://example.com/my/wiki

Create wiki


You can copy an existing wiki to /var/www/wikis/mywiki, but for this example I'll just create a new one:
mkdir -p /var/www/wikis/mywiki
cd /var/www/wikis/mywiki
wik init
Select the type of storage you want and accept the rest of the defaults. (The server options have nothing to do with your Apache setup so its safe to accept the defaults.)

On (at least) Unix/Linux systems, the wiki needs to be owned by the userid that runs the Apache process. For example, on my server the Apache process is owned by www-user, so I do:
chown -R www-user /var/www/wikis/mywiki


Add CGI script


Create a CGI script in your cgi-bin folder:

/var/www/cgi-bin/wiki.cgi
#!/usr/bin/python
#
# Set the above line to the full path of your Python executable

# Set this to the full path where the wiki is stored
WIKIPATH = '/var/www/wikis/mywiki'

# Set this to match the public URL path:
SCRIPT_NAME = '/my/wiki'

# You can set True if desired to enable logging
USE_LOGGING = False

# nothing else to configure -- serve wiki
import wikklytext.wiki.frontend.ws_cgi as ws_cgi
ws_cgi.init(WIKIPATH, USE_LOGGING)
ws_cgi.serve_wiki(WIKIPATH, SCRIPT_NAME)


Make the file executable:
chmod a+x /var/www/wikis/mywiki/wiki.cgi


Configure Apache


Edit your Apache configuration (i.e. httpd.conf, .htaccess, etc.) and add a Location section:
<Location /my/wiki>
    # redirect /my/wiki -> /cgi-bin/wiki.cgi
    RewriteEngine on
    RewriteBase /my/wiki
    # don't change if already rewritten
    RewriteCond %{REQUEST_URI} !wiki.cgi
    RewriteRule /my/wiki/(.*)$ /cgi-bin/wiki.cgi/$1
</Location>


Restart Apache.

Ready to go!


You should now be able to browse to http://example.com/my/wiki and see your wiki. ]]> d2deb5453b6b27507047ecf6f21133e59a37b161 Fri, 02 Oct 2009 14:50:00 +0000 UsingWik UsingWik.html wik is a tool for creating, managing, rendering and serving wikis. It provides an easy to use GUI, but you can also use it from the command line. The command line options are documented here.

Quickstart


Create a standalone wiki server:
$ mkdir /my/test/wiki
$ cd /my/test/wiki
$ wik init
$ wik serve


You can view/edit your wiki at http://127.0.0.1:8000 (assuming you accepted the defaults in wik init)

You can also render your wiki to static HTML:
$ wik render


Wik Reference

Usage
wik command ...

Normally wik assumes that the wiki is in the current directory. If that is not the case you can run it as:
wik -d /PATH/TO/WIKI command


Primary Commands

wik init
Initialize a wiki in the current directory. It will prompt you for information it needs.

You can initialize a wiki by ...
  • Using an existing TiddlyWiki
  • Using an existing set of text (.txt) files.
  • Creating a brand new wiki, with your choice of storage formats:
  • You can read more about these options at WhichFormat?


The wiki will be populated with a default set of items to help you get started.
The configuration is saved to .wik/conf in each wiki directory, should you wish to adjust it later. It is a plain text file.


wik serve
Start a standalone server to provide your content over HTTP with full multiuser editing.

For example, to serve content from /usr/doc/mywiki:
wik -d /usr/doc/mywiki serve
You would then view your wiki through http://localhost:8000
(Using the default server parameters as an example.)

To serve behind Apache, instead of as a standalone server, see BehindApache.

wik render
Render the wiki to a static set of HTML files. This is useful especially if you want to edit your wiki locally (through wik serve) and place the final set of HTML files on a webserver.

wik gui
Launch the GUI "command center". This is a GUI tool that lets you easily manage your locally stored wikis. (This is also the default command if you run wik.exe or wikgui.exe with no arguments.)

Secondary Commands

wik ls
List the contents of the wiki.

wik skip
Interactively edit the list of items that will not be rendered.

wik clean
Remove all generated files and clear out the cache.

wik cache
Interactively edit the list of items that will not be cached.

wik conv
Convert underlying wiki storage to another format. You can freely convert between any of the supported types.
Caveat
When you convert to the TiddlyWiki format, the markup style of your content will changed to TiddlyWiki (since this is the only markup style that a native TiddlyWiki supports). This may alter the presentation of your content somewhat. When converting from a TiddlyWiki, the content type will be left as TiddlyWiki.

Converting to/from a text or SQLite wiki will not alter the content type.


wik makeboot
Add a small bootstrap file to your wiki to help in running BehindApache.

wik trustall
Useful when importing an existing TiddlyWiki. Creates (non-login) accounts for all existing authors and marks them as trusted users. (So that their content will render in full mode instead of safe mode.)

blog comments powered by Disqus

]]> 98277cbffc6004b87b2aab296a1de64631865bfb Sun, 27 Sep 2009 11:23:00 +0000 Apache+mod_python Apache+mod_python.html
Please read before continuing
  • These instructions are for WikklyText 1.9.x. If you are running an earlier version, see BehindApache instead.
  • If you are upgrading from WikklyText 1.6.x or earlier, you can delete the file wikboot.py in your wiki folder. It is no longer used.
This recipe shows how to setup a wiki using Apache and mod_python.

For this example, I'll assume you are using the following locations. Adjust as needed:
Wiki filesystem location
/var/www/wikis/mywiki
Public URL
http://example.com/my/wiki

Create wiki


You can copy an existing wiki to /var/www/wikis/mywiki, but for this example I'll just create a new one:
mkdir -p /var/www/wikis/mywiki
cd /var/www/wikis/mywiki
wik init
Select the type of storage you want and accept the rest of the defaults. (The server options have nothing to do with your Apache setup so its safe to accept the defaults.)

On (at least) Unix/Linux systems, the wiki needs to be owned by the userid that runs the Apache process. For example, on my server the Apache process is owned by www-user, so I do:
chown -R www-user /var/www/wikis/mywiki


Add server script


Create a Python script in your wiki folder:

/var/www/wikis/mywiki/wiki.py
import os
import wikklytext.wiki.frontend.ws_modpy as ws_modpy

# Assuming this script is placed in your wiki root directory, you
# can leave this as is. Otherwise, set it to the full path of your
# wiki folder.
WIKIPATH = os.path.split(os.path.abspath(__file__))[0]

# Set this to your public URL path
SCRIPT_NAME = "/my/wiki"

# set True to enable logging
USE_LOGGING = False

ws_modpy.init(WIKIPATH, USE_LOGGING)

def handler(req):
    return ws_modpy.serve_wiki(WIKIPATH, req, SCRIPT_NAME)


Configure Apache


Edit your Apache configuration (i.e. httpd.conf, .htaccess, etc.) to setup mod_python to serve the wiki:
# set this to your public URL path
<Location /my/wiki>
    SetHandler mod_python
    PythonPath "sys.path + ['/var/www/wikis/mywiki']"
    PythonHandler wiki::handler
    PythonDebug On
    # give a unique name to avoid problems
    PythonInterpreter WikiTestModpy
</Location>


Ready to go!


You should now be able to browse to http://example.com/my/wiki and see your wiki. ]]> 40832c4127fb4d6e51d3df812ae321a16535c25e Sun, 27 Sep 2009 01:45:00 +0000 ApacheIntegration ApacheIntegration.html
Please read before continuing
  • These instructions are for WikklyText 1.9.x. If you are running an earlier version, see BehindApache instead.
  • If you are upgrading from WikklyText 1.6.x or earlier, you can delete the file wikboot.py in your wiki folder. It is no longer used.
Apache+CGI
Simplest integration via CGI.
Apache+CGI+mod_rewrite
Like above but uses mod_rewrite to make nicer looking URLs.
Apache+CGI+mod_rewrite+cgi-bin
A recipe to use if your cgi-bin directory is seperate from your wiki directory. This is the most secure way to run via CGI since you don't have to allow CGI permissions on the wiki folder itself.

Apache+mod_python
Recipe using mod_python. Gives higher performance than the CGI recipes but mod_python is not as widely available across webhosts.

]]> d01a13a9ddd3a91a33f2e80d5157591efd2a3aed Sun, 27 Sep 2009 01:45:00 +0000 Apache+CGI Apache+CGI.html
Please read before continuing
  • These instructions are for WikklyText 1.9.x. If you are running an earlier version, see BehindApache instead.
  • If you are upgrading from WikklyText 1.6.x or earlier, you can delete the file wikboot.py in your wiki folder. It is no longer used.
This recipe shows a very basic CGI setup. I assume that you can run CGI scripts from any location. If that is not true, you might want to read Apache+CGI+mod_rewrite+cgi-bin instead.

For this example, I'll assume you are using the following locations. Adjust as needed:
Wiki filesystem location
/var/www/wikis/mywiki
Public URL
http://example.com/wikis/mywiki/serve.py

Create wiki


You can copy an existing wiki to /var/www/wikis/mywiki, but for this example I'll just create a new one:
mkdir -p /var/www/wikis/mywiki
cd /var/www/wikis/mywiki
wik init
Select the type of storage you want and accept the rest of the defaults. (The server options have nothing to do with your Apache setup so its safe to accept the defaults.)

On (at least) Unix/Linux systems, the wiki needs to be owned by the userid that runs the Apache process. For example, on my server the Apache process is owned by www-user, so I do:
chown -R www-user /var/www/wikis/mywiki


Add CGI script


Create a CGI script in your wiki folder:

/var/www/wikis/mywiki/wiki.py
#!/usr/bin/python
#
# Set the above line to the full path of your Python executable

#--------------------------------------------------------------------
# You PROBABLY don't need to change anything below here, but take
# a quick glance just in case.
#--------------------------------------------------------------------

# If wiki.py is in your wiki directory, you can leave WIKIPATH alone.
# However, if your CGI scripts are in a seperate directory, you'll need
# to set this to point to your wiki path.
import os
WIKIPATH = os.path.split(os.path.abspath(__file__))[0]

# Normally you can leave this set to None, but if needed, you set it like this:
#     My wiki URL = http://example.com/my/wiki/serve.py
#     SCRIPT_NAME = '/my/wiki/serve.py'
SCRIPT_NAME = None

# set True to use logging
USE_LOGGING = False

# nothing else to configure -- serve wiki
import wikklytext.wiki.frontend.ws_cgi as ws_cgi
ws_cgi.init(WIKIPATH, USE_LOGGING)
ws_cgi.serve_wiki(WIKIPATH, SCRIPT_NAME)


Make the file executable:
chmod a+x /var/www/wikis/mywiki/wiki.py


Configure Apache


Edit your Apache configuration (i.e. httpd.conf, .htaccess, etc.) to enable the CGI script to run in the wiki directory:
<Directory "/var/www/wikis/mywiki">
    AllowOverride None
    Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
    # whatever extensions you want to use ...
    AddHandler cgi-script .py
    Order allow,deny
    Allow from all
</Directory>
The procedure for using custom CGI scripts varies widely between webhosts. The above is just one example. Check with your provider for additional documentation if needed. If you have a better suggestion please post to the MailingList.


Ready to go!


You should now be able to browse to http://example.com/wikis/mywiki/serve.py and see your wiki.

If you want to use a nicer URL scheme that hides the CGI script name, take a look at Apache+CGI+mod_rewrite.]]> 034587ee76c0cdd930f49b7f15a2f3a02b16cae4 Sun, 27 Sep 2009 01:44:00 +0000 Apache+CGI+mod_rewrite Apache+CGI+mod_rewrite.html
Please read before continuing
  • These instructions are for WikklyText 1.9.x. If you are running an earlier version, see BehindApache instead.
  • If you are upgrading from WikklyText 1.6.x or earlier, you can delete the file wikboot.py in your wiki folder. It is no longer used.
For this example, I'll assume you are using the following locations. Adjust as needed:
Wiki filesystem location
/var/www/wikis/mywiki
Public URL
http://example.com/my/wiki

Notice two things here that are different from the basic CGI setup:
  • The public URL has nothing to do with the filesystem path.
  • The actual CGI filename is hidden.

Basic CGI Setup


First of all, get a basic CGI setup working using Apache+CGI. We will build on top of that setup below.

Add mod_rewrite


In your Apache configuration file, add a new section (leaving everything else as-is):
<Location /my/wiki>
    # redirect /my/wiki -> /wikis/mywiki/wiki.py
    RewriteEngine on
    RewriteBase /my/wiki
    # don't change if already rewritten
    RewriteCond %{REQUEST_URI} !wiki.py
    RewriteRule /my/wiki/(.*)$ /wikis/mywiki/wiki.py/$1
</Location>


Modify CGI script


Change the SCRIPT_NAME parameter in your CGI file:

/var/www/wikis/mywiki/wiki.py
SCRIPT_NAME = '/my/wiki'


Ready to go!


You should be able to browse your wiki at http://example.com/my/wiki ]]> fd2c5260d06dbe26b07391063a9dab0f5f89f7f9 Sun, 27 Sep 2009 01:44:00 +0000 BehindApache BehindApache.html
Check your version
These instructions are for WikklyText 1.6.0 and earlier. If you are running a later version, see ApacheIntegration instead.


First, ensure you have installed the Python module. Running a WikklyText wiki behind Apache via mod_python is straightforward. Here is an example:
Wiki location on filesystem:
/MY/WIKI/PATH
Desired URL:
/WIKI/PATH

  • First, add a small bootstrap module to your wiki folder:
    cd /MY/WIKI/PATH
    wik makeboot
  • Point Apache to your wiki (i.e. inside a VirtualHost container):
    <VirtualHost>
        ... assuming this is the root section ...

      <Location /WIKI/PATH>
        PythonPath "sys.path + [r'/MY/WIKI/PATH']"
        SetHandler python-program
        PythonHandler cherrypy._cpmodpy::handler
        PythonOption cherrypy.setup wikboot::start_modpython
        PythonDebug On
        # I recommend setting "MY_WIKI_NAME" in the next line
        # to give each wiki a unique name.
        # This avoids weird problems caused by mod_python caching.
        PythonInterpreter MY_WIKI_NAME
      </Location>
  • Edit wikboot.py (in your wiki folder) and set WEBPATH="/WIKI/PATH".
  • Restart Apache and your wiki should work.
  • For testing purposes, you can also run a standalone server:
    cd /MY/WIKI/PATH
    python wikboot.py


Troubleshooting


Note that your wiki needs to be writeable by the userid that Apache runs under. The best method (assuming the Apache user is apache-user) is:
chown -R apache-user /MY/WIKI/PATH


If that is not possible, then you'll have to make it world writeable:
chmod -R a+rw /MY/WIKI/PATH


blog comments powered by Disqus

]]> a3f1393c940773c095ebb33aa38ce2755988379b Sun, 27 Sep 2009 01:29:00 +0000 WritingPlugins WritingPlugins.html
Module wikklytext.plugins

WikklyText Plugins


The Plugin API allows you to extend the functionality of WikklyText in several ways:
  • You can add new macros than can be called from wikitexts as <<mymacro ..>> (link)
  • You can add functions that appear in the namespace of <?py code embedded in wikitexts. (link)
  • You can attach extra styling information (CSS) to the rendered document (link)

Click a link for more, or read on for full details.

Creating new macros


Macros are ordinary Python functions with the following calling sequence:
def mymacro(context, ...):
    ...


Where context is a WikContext (ref: wikklytext.base) and the remainder of the args are passed from the macro call. For example:
<<mymacro 123 456 "abc">>


Would call:
def mymacro(context, a, b, c):
    # a.text = "123"
    # b.text = "456"
    # c.text = "abc"


Note that each passed argument is an Element so you use .text to get the text portion. (More general macros might want to deal with arbitrary ElementTrees as arguments, but text args are the simplest and most common.)

Macros can return any of the following:
  • An Element
  • A unicode string
  • A byte-string
  • A list/tuple of any of the above types.

Here is what a typical plugin looks like. Let's assume:
  • My plugin is named myplugin.
  • I'm defining two macros that are safe for anyone to call named happy and nice.
  • I'm defining two macros that only trusted users are allowed to call named evil and bad.

My __init__.py would look like this:
plugins/myplugin/__init__.py
__safe__ = ['happy', 'nice']
__unsafe = ['evil', 'bad']

def happy(context, ...):
    ...
    
def nice(context, ...):
    ...

.. etc. ..


(In a real plugin, you'd probably split your code up into multiple files. The above example shows all code being placed in __init__.py for simplicity.)

Creating embedded functions


Embedded functions are ordinary Python functions that are available by default in the global namespace of embedded Python code (<?py). They do not get a context arg, and are called like any other function (and may return any value).

To add functions to the embedded namespace, add their names to the __embed__ list at the top of your module (similar to __safe__ and __unsafe___ above).

Adding styling (CSS) information


You might find yourself defining new CSS classes as part of your macros. While it is certainly possible to tell your macro users to add your new styles to their wiki StyleSheet, it is much more convenient to provide the classes automatically.

To do this, simply define a module level variable __css__ that is a string with the styling information to be added to the document <HEAD>. For example:
__css__ = '''
    div.myclass1 {
        color: red;
    }
    '''


The string will be added to a <style> tag when creating the HTML document.

A simple example


Here is a simple complete example:

  1. First, create a folder hello under plugins/ in your wiki folder.
  2. Create a file plugins/hello/__init__.py
    '''
    This is just like any other Python package where you have __init__.py
    defining the interface.

    __init__ may define any/all/none of: __embed__, __safe__ and __unsafe__.
    '''
    __embed__ = ['hello_embedded']
    __safe__ = ['hello_safe', 'hello_box']
    __unsafe__ = ['hello_unsafe']
    __css__ = '''
        div.hellobox {
            background: yellow;
            color: black;
            border: 3px solid blue;
            padding-left: 3em;
            }'''
            
    '''
    For real code you'd probably split these functions into their
    own files and just import them here.
    '''
    def hello_safe(context, msg):
        return "Hello safe, message=%s" % msg.text

    def hello_unsafe(context, msg):
        return "Hello unsafe, message=%s" % msg.text

    def hello_box(context, msg):
        "A slightly more complex example ..."
        from wikklytext.plugapi import DIV, Text, eval_wiki_text

        d = DIV('hellobox')
        d.append(eval_wiki_text(context, msg.text))
        return d
        
    def hello_embedded(msg):
        return "Hello Embedded, message=%s" % msg.text
  3. Finally, create a new wiki item with this text:
    <?py
    def hello(context, msg):
       return hello_embedded(msg) # auto-added to embedded namespace
    ?> 

    /% Minimal example, showing how args are passed. %/
    !!!From ''<$py''
    <<hello "Embedded message!">>

    !!!From ''<nowiki><<hello_safe>></nowiki>''
    <<hello_safe "Safe message!">>

    !!!From ''<nowiki><<hello_unsafe>></nowiki>''
    <<hello_unsafe "Unsafe message!">>

    !!!From ''<nowiki><<hello_box>></nowiki>''

    <<hello_box '''This text should be inside a yellow box. 
    This macro uses a custom CSS class. All
    __wikitext__ //styling// @@markup@@ works
    here as well.'''>>


Save the item and you should see that it works.
Classes
WikPlugins(object)
Returned from load_plugins(). All currently loaded plugins.

Attributes:
safe,unsafe
Dicts of {name: func} where name can be used as <<name ...>>. Mapped from __safe__ and __unsafe__ attrs defined in modules.
embed
Dict of {name: func} where name will be inserted into the embedded namespace for <?py code in wikitexts. Loaded from __embed__ attr defined in module.
css
CSS styles to be added to <HEAD> (text).
wsgi_apps
Dict of WSGI applications defined by plugins, as: URL: handler. Each URL is of form /api/plugins/NAME/SUBURL where NAME is the name of the plugin and SUBURL is the URL path the plugin defined.
wsgi_macros
Like safe and unsafe, a map of {name: func}. wsgi_macros are just like safe & unsafe macros, except that they receive a WSGI-like environment instead of a WikContext as their first argument.
modules
List of (name, module) for all loaded plugins. (This is for information purposes; all functional data has been pulled out and organized in the other attributes here.)
Functions
load_plugins(plugdirs=None, namespace='plugins')
A little wrapper around real_load_plugins() that catches import errors — namely errors due to being unable to import 'imp'. Was initially created to workaround the lack of the imp module under GoogleAppEngine.

XXX TODO - make loading of plugins work under GAE, etc., instead of just returning an empty set of plugins.

blog comments powered by Disqus



]]> 3fc33060fda39ad54cfafae897a2331ef4cad250 Mon, 17 Aug 2009 11:51:00 +0000 DrupalPlugIn DrupalPlugIn.html Requires: First, ensure you have installed the Python module.

You install WikklyText just like any other Drupal module:
  1. Download sources
    Drupal 5 drupal5-WikklyText-1.6.0.zip
    Drupal 6 drupal6-WikklyText-1.6.0.zip
  2. Unpack the WikklyText package under either modules/ or sites/all/modules (you should end up with a directory modules/wikkly_fmt, or sites/all/modules/wikkly_fmt).
  3. Go to Admin|Site Building|Modules and enable the WikklyFormat module.
  4. Go to Admin|Site Configuration|Input Formats
    1. Click Add Input Format
    2. Select WikklyText, Full Mode or WikklyText, Restricted Mode (but not both at the same time).
    3. Name the format something like WikklyText, Full or WikklyText, Restricted (as a reminder to yourself).
    4. Select which Roles may use it
      CAUTION
      Full Mode is for trusted users only. Full Mode allows the user to execute arbitrary code (by design), and should only be given to people you would trust to access the PHP code input format (for example).

      Restricted Mode is for all other users. It can do 95% of what you would normally want to do anyways, without allowing arbitrary code execution or calling unsafe macros.

      WARNING: As of this writing, Restricted Mode has had very limited testing "in the wild". Is is believed to be safe, but to be cautious, you might not want to allow untrusted users to access even Restricted Mode until it has been more widely tested.
    5. There is no need to add additional filters to the input chain when using a Wikkly format. Adding filters in Full Mode will remove necessary document structure. You can add filters in Restricted Mode if you prefer, but WikklyText is designed to be safe on its own.
  5. When creating content, select the desired WikklyText filter under Input Format as shown below:

    cap_selfmt.png

    blog comments powered by Disqus

]]> 312264b8b6f7bcc65842e111f084b8cc898a17fa Sun, 16 Aug 2009 23:55:00 +0000 InstallPythonPackage InstallPythonPackage.html setuptools installed, then simply run:
easy_install -U wikklytext


Else, download the sources:
Source (.tar.gz) WikklyText-1.6.0.tar.gz
Source (.zip) WikklyText-1.6.0.zip
Unpack, chdir to unpacked directory and ...
python setup.py install

Any missing dependencies will be automatically downloaded and installed.

Ensure that Python's Scripts directory is in your PATH if you want to use the command-line utilities. (For example, if Python is installed to c:\Python25 you would add c:\Python25\Scripts to your PATH.)

Previous version:
Source (.tar.gz) WikklyText-1.5.0.tar.gz
Source (.zip) WikklyText-1.5.0.zip

blog comments powered by Disqus

]]> cc66c58a36ab67900bde44dc052fd709ff0730a0 Sun, 16 Aug 2009 23:54:00 +0000 GettingPlugins GettingPlugins.html
If you write a plugin and would like it listed here, send a note to the MailingList.

Installing Plugins


Plugins are packaged as regular ZIP files. To use a plugin, simply unzip it under the plugins directory in your wiki. So for example, if your wiki lives in /MY/WIKI, then unpacking a plugin foo would leave you with a new folder /MY/WIKI/plugins/foo. You should be able to use the plugin immediately after unpacking it.

hello


The traditional "Hello World!" plugin. This is a minimal sample plugin meant to demonstrate the WikklyText plugin API. If you want to write your own plugins, this is a good place to start. Of course, you'll also want to read the documentation on WritingPlugins.

Downloadhello (1.0)
Once unpacked, see the README file for usage notes. ]]> 7133c78e6e26128fa8f34319201c0a45b54448f3 Thu, 02 Oct 2008 01:11:00 +0000 BrowserIssues BrowserIssues.html
As of this writing, WikklyText is actively tested against these browsers (listed roughly in order of frequency of testing):
BrowserVersionPlatform
Firefox 3.0.3 Windows
Internet Explorer 7.0 Windows
Opera 9.52 Windows
Safari 3.1.2 Windows
Chrome 0.2.149.30 Windows
w3m 0.5.1 Windows/Cygwin
lynx 2.8.6 Windows/Cygwin
links 1.0.0pre20 Windows/Cygwin

blog comments powered by Disqus

]]> 9bf46c3a9b04c85dbeee48664a2dea614a212d63 Mon, 29 Sep 2008 02:16:00 +0000 ConversionDemo ConversionDemo.html
  • RandomPedia

    blog comments powered by Disqus

    • ]]>     743079db11b61283c00e3dfc50ce6d56bff4c6e9 Sun, 14 Sep 2008 12:53:00 +0000     Requirements Requirements.html Core:
    • Python 2.3+
      The following dependencies will be automatically downloaded when you install WikklyText. They are listed here for reference.
    To use GUI: To use with Drupal: To use BehindApache: ]]>     a842fb3fa3284f5e2fba17fc15f0131378fe708c Tue, 12 Aug 2008 04:12:00 +0000     WhichFormat? WhichFormat_.html
  • A flat set of text files
  • A TiddlyWiki
  • An SQLite database

    • What are the pros and cons of each?
    Flat text files
    In this case, each wiki entry is stored in its own text (.txt) file. This makes it very easy to edit your wiki with a plain text editor as well as through the WikklyText wiki interface. In terms of speed, this falls between the SQLite and TiddlyWiki format.
    TiddlyWiki
    By storing your content in a TiddlyWiki, your wiki content becomes a self-contained wiki that you can open & edit it directly in your browser just as with any TiddlyWiki. The downside is that this is the slowest format.
    SQLite
    This is the fastest storage format. The downside is that it is only editable through a WikklyText server.

    Don't worry too much about choosing the "right" format. You can always change to another format later via the wik conv command.

    Summary table
    FormatSpeedSelf-contained wiki?Supported markup
    styles1
    TiddlyWiki Slowest Yes TiddlyWiki
    Text files Medium No TiddlyWiki
    WikklyText
    SQLite Fastest No TiddlyWiki
    WikklyText
    Footnotes:
    1. If you want to ensure no formatting changes occur when moving content between the different formats, choose the "TiddlyWiki" markup style when creating content.

      blog comments powered by Disqus

    ]]>     f0b5463458a3e63ef5f992ca3952022e11e10de8 Tue, 12 Aug 2008 04:11:00 +0000     MailingList MailingList.html
    The list is hosted at Google Groups: WikklyText Mailing list

    You can also post comments on many pages here (for longer questions/issues, though, please use the mailing lists).


    ]]>     9fcbfc4e4a622c25291f35fc8d2c73d2813ad326 Tue, 12 Aug 2008 04:09:00 +0000     WikExeWin32 WikExeWin32.html DescriptionFileCommand-linewik.exe (for win32)GUIwikgui.exe (for win32)Which one do you want?
    • These programs are virtually identical. The only difference is that wikgui.exe does not pop up a command shell when you run it, so is better for pure GUI usage.
    • You might like having both: wikgui for point-and-click usage, and wik for doing admin tasks.

      If you've downloaded these before you may need to clear your browser cache to ensure you get the updated version(s).
    No installation is required, just place wik.exe and/or wikgui.exe anywhere convenient (for command-line usage, you might want to place them in your PATH).

    Now you are ready to start UsingWik or create a WikiOnAStick.

    Issues?


    If you have problems ...
    • Make sure you did not rename the executables. Save them exactly as wik.exe or wikgui.exe. Due to py2exe behavior, the filename must not change.
    • Make sure you did not save them directly to root of your C: drive (i.e. as c:\wik.exe or c:\wikgui.exe). They have to be stored in a subfolder. Like above, this is due to py2exe behavior.
    • For Windows 2000 and earlier, if you get an error about missing GDI+, then you need to download the GDI+ SDK Redistributable. Unpack it to the same folder where you saved wikgui.exe.
    • You must have MSVCR71.DLL and MSVCP71.DLL on your machine. If either of these are missing, wik.exe and wikgui.exe will fail to run.
      Unfortunately, the Microsoft license does not appear to allow redistribution of either MSVCR71.DLL or MSVCP71.DLL, so you will have to search for them.

      Be sure to check the md5sums of any DLL files before running them. For reference, the md5sums of the legitimate files are:
      Filenamemd5sumSearch link
      MSVCR71.DLL86f1895ae8c5e8b17d99ece768a70732search
      MSVCP71.DLL561fa2abb31dfa8fab762145f81667c2search
      The last time I checked, DLL-files.com had the legitimate files.
    • If you are running Windows 95/98/Me then you may also need to download w9xpopen.exe and place it in the same folder as wik.exe and/or wikgui.exe.

      blog comments powered by Disqus

    ]]>     74f7e559970b45c648ea6114e418a2bcd5f97158 Tue, 12 Aug 2008 04:06:00 +0000     WikiOnAStick WikiOnAStick.html
    If you are running Windows, here is a quick way to get started:
    • Download wikgui.exe from WikExeWin32 and place it on your USB drive.
    • Run wikgui.exe.
    • Click Add to create a new wiki.
      I recommend choosing the "Tune for USB usage" option, when prompted. This will minimize writes to the USB drive. (See also OptimizeForUsbUsage)
    • When finished, double-click on the new wiki to launch and browse it.

    Command Line Usage


    If you prefer to use the command line instead of the GUI, here is the recipe:
    • Download wik.exe from WikExeWin32 and place it on your USB drive.
    • Lets assume your USB drive is E: and you want to create a wiki called "MyFirstWiki". Open a command window and run:
      e:
      md MyFirstWiki
      cd MyFirstWiki
      e:\wik init
    • Now, answer a few questions about how you want to setup your wiki. When you are finished, run:
      e:\wik serve
    • Now (assuming you accepted the defaults) point your browser to: http://127.0.0.1:8000, and you should be off and running!

      blog comments powered by Disqus

    ]]>     16436e79b33332e355aa89747ac30a117e9a5e59 Tue, 12 Aug 2008 04:05:00 +0000     GettingWikklyText GettingWikklyText.html
  • If you want to try it out without installing Python, and you are running Windows, WikExeWin32 is a quick way to get started.
  • Otherwise, install the Python package.
  • To use with Drupal, get the DrupalPlugIn.
    • ]]>     7565562c9c3499cd0a7ffe79b05a85fd6c025955 Tue, 12 Aug 2008 04:05:00 +0000     Welcome! Welcome!.html WikklyText?
    • It provides a lightweight, portable, extensible wiki language, compatible with TiddlyWiki
      (see also: MarkupReference).
    • It is easily used as a WikiOnAStick for keeping a personal wiki.
    • It can be used BehindApache to serve a multiuser wiki.
    • It can be plugged into Drupal allowing you to write in WikklyText markup on your existing Drupal site.
    • It provides "Safe" and "Full" modes: In "Safe" mode, the user is restricted to only calling safe macros, no HTML injection is possible, and the generated text is filtered to preclude XSS issues. In a server setting (e.g. Drupal or Apache) this allows untrusted users to write WikklyText content without endangering system security.
    • It is extensible, allowing both embedded Python code in wikitexts (<?py ... ?>) as well as providing an easy to use plugin API.
    • It is a modular Python library that you can use to build your own wikitext rendering applications. You can render to both HTML and XML for flexibility.
    • It is provided under a free license.

    To view some sample content, see the ConversionDemo. ]]>     81aa1022e1fcea429e2a05c3e2f240cbdaebd0ba Sun, 10 Aug 2008 21:07:00 +0000     WhyWikklyText WhyWikklyText.html
  • First, I wanted to experiment with doing more Pythonic things within a TiddlyWiki-like framework. An obvious expression of this is the ability to embed Python code in wikitexts. With this addition, wikitexts now have access to the full Python library, and issues like "how do I talk to a database?" become moot.
  • Secondly, I liked the basic TiddlyWiki markup language enough that I wanted to enable it to be used in more contexts. I was tired of using domain-specific markup languages (hand-edited HTML vs. TinyMCE vs. reStructuredText vs. ...) and wanted to move to a single standard for my own content. To this end, WikklyText provides highly modular pieces for rendering, store management, etc., with the hope that others will be able to mix & match pieces to build their own tiddly-speaking applications.

    • ]]>     9e9ff1d9da61e4903ba202fc675bb0805b70a4a7 Wed, 18 Jun 2008 00:37:00 +0000     OptimizeForUsbUsage OptimizeForUsbUsage.html WikiOnAStick from a USB drive, you probably want to minimize the number of writes to the device. You can do that making the following settings on the Wiki Admin page:
    • Set Session Storage to ram.
    • Set Render Cache to Off
    • Set MetaDb to Off

    ]]>     1957616f571c972355f9501893453b4f56b373a4 Mon, 16 Jun 2008 00:52:00 +0000     Patch: cherrypy-3.1.0rc1-console-handler Patch- cherrypy-3.1.0rc1-console-handler.html diff -u -r CherryPy-3.1.0rc1/cherrypy/__init__.py fm-CherryPy-3.1.0rc1/cherrypy/__init__.py
    --- CherryPy-3.1.0rc1/cherrypy/__init__.py    2008-05-17 15:34:25.000000000 -0500
    +++ fm-CherryPy-3.1.0rc1/cherrypy/__init__.py    2008-06-12 11:33:48.467036800 -0500
    @@ -181,7 +181,8 @@
         del win32
     except ImportError:
         engine = process.bus
    -
    +    _console_control_handler = None
    +    
     
     # Timeout monitor
     class _TimeoutMonitor(process.plugins.Monitor):
    diff -u -r CherryPy-3.1.0rc1/cherrypy/_cpmodpy.py fm-CherryPy-3.1.0rc1/cherrypy/_cpmodpy.py
    --- CherryPy-3.1.0rc1/cherrypy/_cpmodpy.py    2008-05-17 15:34:26.000000000 -0500
    +++ fm-CherryPy-3.1.0rc1/cherrypy/_cpmodpy.py    2008-06-12 11:34:11.149164400 -0500
    @@ -97,7 +97,8 @@
                                 "tools.ignore_headers.headers": ['Range'],
                                 })
         
    -    cherrypy._console_control_handler.unsubscribe()
    +    if cherrypy._console_control_handler is not None:
    +        cherrypy._console_control_handler.unsubscribe()
         cherrypy.engine.autoreload.unsubscribe()
         cherrypy.server.unsubscribe()]]>     bd1049bd9c33608decc7591a5fcb7255bd503a84 Thu, 12 Jun 2008 16:47:00 +0000     WikGuiConfigFolder WikGuiConfigFolder.html wik and wikgui are intended to work well as a "portable" applications. This means that they are careful not to write anything to the registry and won't store any configuration files on your computer unless you ask them to. You have three options for storing your configuration data:
    User folder
    Configuration will be stored in the standard host OS location for user data.
    Examples:
    • XP: c:\Documents and Settings\USER\Application Data\WikklyText
    • Vista: c:\Users\USER\AppData\Roaming\WikklyText
    • Linux/POSIX: ~/.WikklyText
    Executable folder
    Configuration will be stored in the same location as wik.exe/wikgui.exe
    Other folder
    If you don't like either of these options, you can run wik (or wikgui) like this to specify a location:
    wik --cfgpath="c:\My\Folder\Location"


    Tip:
    If you want to run off of a USB drive and not touch the host computer, you'll want to choose either Executable folder or Other location.

    ]]>     bf95563df70b21c5ecbc62250223166b7156700f Thu, 12 Jun 2008 02:30:00 +0000     twextract twextract.html
    Deprecation Warning
    twextract is deprecated. It has been superceded by wik. It will be removed at some point unless there is significant interest in keeping it around (let me know via the MailingList if that is the case for you).


    The twextract utility converts a TiddlyWiki into a flat set of XML & HTML files. This can be useful for ...
    • Serving your TiddlyWiki content as a lightweight set of pages instead of each user having to download the entire wiki.
    • Serving your TiddlyWiki content in a Javascript-restricted environment.
    • Serving your TiddlyWiki to users with limited browser capability, for example mobile phone users.

    Run twextract by giving it a TiddlyWiki .html file and an output directory. For example, to convert c:\tiddlywiki.html, placing results in c:\output:
    twextract c:\tiddlywiki.html c:\output


    You can view an example here: TiddlyWiki Home Page, converted to HTML.

    ]]>     6411cb4dd5ab183a94e1aa9c8ca4b2d1110f6327 Thu, 05 Jun 2008 13:16:00 +0000     ServingFiles ServingFiles.html files/ directory under your wiki folder. WikklyText will serve any files that are located there, including in any subdirectories (no matter how deeply nested).

    Here are some examples. My wiki root folder looks like this:
    wiki/
        files/
             testing/
                     htmlfile.html
                     imagefile.png
                     textfile.txt


    First, serving an HTML file:
    • HTML file
      Markup: [[HTML file|files/testing/htmlfile.html]]


    WikklyText knows to set the MIME type correctly so files will render (or not) as they should.
    • Text file
      Markup: [[Text file|files/testing/textfile.txt]]


    Image files:
    • Inline image: files/testing/imagefile.png
      Markup: [img[files/testing/imagefile.png]]
    • Image with link: files/testing/imagefile.png
      Markup: [img[files/testing/imagefile.png][http://wikklytext.com]]
    • Link to image: Image

    The benefits of the file-serving area are:
    • You can make links to file content that work the same for both standalone wikis and wikis running behind a webserver.
    • You can move your wiki around without breaking links to file content.
    • File download activity will be included in your logs for easy reference.
    ]]>     8c8d1c44a848194ccd012dfd847ff05743deb3a1 Wed, 12 Mar 2008 02:09:00 +0000     AboutTheseDocs AboutTheseDocs.html TiddlyWiki you'll notice that WikklyText wikis use the same naming scheme. This is done so that you can move content freely between a TiddlyWiki and a WikklyText wiki. (See the wik conv command in UsingWik.)

    Much of the time, this site will be running a prerelease version of WikklyText. Don't be surprised to see a version number (on the link at the bottom) that is not yet available for download. All features will be included in the next stable release.]]>     0127e3f1304ff5626fdddb2b5baf2cc2abcf7763 Mon, 10 Mar 2008 03:13:00 +0000     Wikkly2HTML Wikkly2HTML.html You can accomplish this same task with the wik command-line tool. wikkly2html has been around longer, but is being superceded by wik.

    The wikkly2html utility converts WikklyText files to HTML:
    1. wikkly2html --css -o OUTFILE.html INFILE.txt
    2. Notes:
      1. You can pass -m safe on the command line to get the same safety features you get with the Drupal Safe mode.
      2. Try running wikkly2html with no parameters to see full help.

    ]]>     c2140f366a98ce00151afede6e5622f4c0ba4560 Mon, 11 Feb 2008 21:00:00 +0000     WhatNow WhatNow.html
    UsingWik
    Use the wik standalone tool to create, manage, render and serve full blown wikis.
    Unless you are a programmer, this is probably what you want to use!
    MarkupReference
    A complete reference to the WikklyText markup language

    For programmers

    WikklyTextApi
    Documents the primary entry points.

    Other/older tools

    wikkly2html
    Renders a single text file at a time.
    twextract
    Tool for converting a TiddlyWiki to standalone HTML (superceded by wik).

    ]]>     4d12e04f6c470bd5b422d8e97ca2455b35367dc3 Mon, 04 Feb 2008 12:22:00 +0000     WikklyTextApi WikklyTextApi.html

    WikklyText_to_XML


    This is probably the best entry point for your own code to use. It converts a wikitext string into XML markup, ready for processing into whatever final format you choose.
    from wikklytext import WikklyText_to_XML
    (xml,context) = WikklyText_to_XML(content, encoding, safe_mode, 
                                      setvars=None, max_runtime=-1, 
                                      url_resolver=None, tree_posthook=None)


    Inputs:

    content
    Wikitext (Unicode), usually from wikklytext.base.load_wikitext().
    encoding
    Desired output encoding (i.e. 'utf-8')
    safe_mode
    True/False, whether to use Safe mode.
    setvars
    Variables to set into WikContext, as dict of: name: str, unicode or int 'name' can have a leading '$' to set sysvars.
    max_runtime
    Maximum time (in seconds) to run, or -1 for unlimited.
    url_resolver
    URL resolver, see wikklytext.base for info.
    tree_posthook
    Hook to call after ElementTree is complete, before generating XML. Will be called as:
    tree_posthook(rootnode, context)
    Hook should modify tree in-place.

    Returns:
    (xml, context)

    Where:
    xml
    Generated XML as an encoded bytestring
    context
    WikContext that was used, in case user wants to inspect it.
    ]]>     d536a55d0343f2fcc2807b7b2acbb9d123d64af4 Mon, 04 Feb 2008 11:26:00 +0000     License License.html GPL v2.

    LICENSE
    The WikklyText suite

    Copyright (C) 2007,2008 Frank McIngvale

    Contact: fmcingvale@boodebr.org

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.


    ]]>     a76a253139e7125a7d8702322da0d74f8606629a Mon, 28 Jan 2008 02:58:00 +0000     FAQ FAQ.html
    ]]>     373b759207b7e433df9a355370ed34fcf5cceab7 Fri, 23 Nov 2007 20:57:00 +0000     NoCacheExample NoCacheExample.html
    To prove it is regenerated, here is a timestamp: Wed Aug 1 21:08:42 2012




    ]]>     33146183fde061a8761dba1d74f6003f08f8f0b2 Sat, 20 Oct 2007 13:20:00 +0000