Unfinished Content This page needs some work; contributions are welcome!
A Pipp site starts as source code, which is a directory of .pip files and supporting files, such as images. Running Pipp builds the source into static HTML for deployment to a web server. The web server does not need to have Pipp installed. For convenience during development, Pipp also has a built-in web server that performs on-demand building.
.pip files are very similar to HTML files, but have extra tags that are processed by Pipp. The build process involves applying an XSLT stylesheet to each .pip file. The stylesheet is tailored to each individual website, and based on a standard template included with Pipp. Pipp provides a number of XSLT extension functions to be called from the template; these assist with common web development tasks. Pipp also provides the framework for calling the XSLT transforms as needed.
Note: If you're using Windows, it is easier to use the Pipp Windows Installer. Manual installation is required on other platforms, and if you want to use the development version, or modify the Pipp source code.
The following dependencies are required:
- Download Pipp Source Code
- Extract the archive into a suitable directory
- Add the directory to your path
To check this worked, at a command prompt or shell window, type "pipp.py -?". This should produce a help screen describing the command line options.
To launch example site...
- Go into the directory and type "pipp.py -s ."
- Browse to http://127.0.0.1:8080/
You can get a checkout of the latest development version from the Subversion repository at Google Code:
svn checkout http://pipp.googlecode.com/svn/trunk/ pipp
Be aware that this may not be as stable as the release version.
The directory for a Pipp site always has the following:
index.pip - the front page
pipp.xsl - the stylesheet used to transform .pip files to .html files
pipp.xml - this is generated by Pipp and contains information on all the pages in the site
out - a directory created by Pipp, that contains the generated web site
Within .pip files, relative and absolute paths can be used. Absolute paths start from the project root directory; it is not possible to reference files outside this. This is deliberate, to encourage self-contained source code. If necessary, you can use symbolic links to work around this restriction.
A simple .pip file looks like:
This is my content
TBD: explain exports and body
Inside the body, the following tags will be processed by Pipp, in addition to any specific rules the site stylesheet: TBD - explain these (link to XSLT API?)
- pipp-child @src
- pipp-file @src
- pipp-child-file @src @title
- pipp-code @src
- pipp-map-view @src
- pipp-img @src ...
- pipp-thumb @src @width/@height ...
It was decided to avoid requiring XML namespaces in .pip files. This avoids including a namespace definition in every .pip file.
A page can export any variables it likes.
If "link" is not explicitly exported, Pipp automatically exports the absolute path to the output HTML file.
In general, all pages will export "title".
Your page template
Any rewrites you want, e.g. graphical h1
Don't start from scratch - use either minimal_pipp.xsl or copy a more detailed example.
Usage: pipp.py [options] project_root
-h, --help show this help message and exit
-s, --serve Start a web server that publishes the project; this is
useful for development
-p PORT, --port=PORT Specify port for the web server (default 8080)
-l LISTEN, --listen=LISTEN
Specify the listening address for the web server
-f, --full Initiate a full rebuild of the project
-v, --verbose Produce more verbose output
- Include the file in the website; it will appear in the site hierarchy as a child of the current file. The file must be valid XML as it will be parsed as a .pip file.
- pipp:child-file(file_name, title)
- Copy the file from in-root to out-root. This is similar to pipp:file, however the file will be included in the site hierarchy as a child of the current file. This is the usual way to include download packages in the website.
- pipp:code(file_name, code, lexer, docss)
- Include a syntax-highlighted source code file in the HTML output. The highlighting is done by Pygments. You can specify either the name of a file to use, or a string. The "lexer" parameter specifies the pygments lexer to use; this must be specified for inline blocks. For files, if not specified, it is determined automatically using the file extension. If "docss" is set to "1", a CSS file with the pygments default colours is automatically generated. If you do not specify docss, you need to include your own CSS rules.
- pipp:export(name, value)
- Add a variable to the current file's export table. Other files will be able to access this variable using pipp:import, pipp:import-join or pipp:map-view. Multiple variables with the same name are permitted but not recommended. It is very common to export the file's title, so site maps and navigation bars can be created.
- pipp:export-depend(path, name)
- Marks the current file as dependent on a variable exported from another file. This needs to be called appropriately in XSLT templates used by map-view, for dependencies to work correctly. It doesn't need to be called from the main stylesheet; pipp:import and pipp:import-join mark the dependency automatically.
- Copy the file from in-root to out-root. The file will not appear in the site hierarchy. This is the usual way to include images or other binary files in the website. file_name can be a directory, which is copied in full, including all files and subdirectories.
- Return the absolute path to the current output file.
- Return the modification date and time of the current input file. The time_format parameter must be a format string suitible for passing to the Python time.strftime function.
- pipp:gtitle(font, height, texture, bgcolor, text)
- Generate an image containing styled text. The font is a path to a .ttf file, the height is is pixels and the texture is a path to a image file. The bgcolor should be set to roughly the colour of the background the image will appear on; this is necessary to make anti-aliasing work correctly.
- Return the width of the image, in pixels. The formats supported are those supported for reading by the Python Imaging Library.
- Return the height of the image, in pixels. The formats supported are those supported for reading by the Python Imaging Library.
- Retrieve a variable from the current file's export table. If it is not defined in the current file, search up the site hierachy. If none of the ancestors define the variable then raise an error. This is useful for controling properties that are usually passed from parent to child, such as CSS stylesheet names.
- pipp:import-join(name, separator)
- Retrieve a variable from the current file and its ancestors' export table. All the variable values are joined into a single string using the separator, with the value from the root file appearing first. This is useful for constructing a long title string, which informs the used of their position in the hierarchy.
- Generate a customised view of the page hierarchy. This is useful for automatically generating navigation bars, site maps, contents pages and more. The specified stylesheet is applied to
pipp.xml and the output is included in the current document. For partial builds to work correctly, the stylesheet must explictly register dependencies, by calling pipp:export-depend.
- Return a relative path to the file. This is usually only useful with absolute file names as relative file name are return unchanged. Using relative paths makes reorganising the website much easier compared to absolute paths.
- pipp:thumbnail(file_name, width, height)
- Generate a thumbnail of the image with the specified size. The function returns the file name of the generate image. If the original image is called xxx.yyy the thumbnail will be called xxx_thumb.yyy. The formats supported are those supported for writing by the Python Imaging Library. You may specify width or height explicitly, or pass one value as zero. If you only specify one dimension, the other will be calculated to preserve the aspect ratio of the original image.