rapple faq

if you have a question just ask ;)

general

• what is rapple ? rapple is a lightweight XML based tool that permits web authors to produce standards based web content of a consistent and high quality. it is based on the premise that the use of plain XHTML sources along with XSLT for styling makes for good websites.
• what does rapple actually do ? rapple converts HTML sources into XHTML, an XML variant of HTML, and then transforms these using an XSLT stylesheet to produce a website. in addition to simply applying a house style to source files rapple also performs other functions. for example rapple has a feature called "indexing" where it can read the contents of a directory and generate an index file from extracts of each of the source files it finds in the directory. rapple can also perform other interesting tasks such as context highlighting, storage of meta data in a MySQL table and checking links of completed websites. see the overview summary and features list for more details.
• rapple does all that on its own ? well not really, rapple gets some help from existing open source tools. for example rapple uses the tidy HTML and the expat XML parser libraries alongside PCRE for string processing. in addition rapple also requires an XSLT processor such as Sablotron or libxslt.
• what are X(HT)ML and XSLT and why do I need to know about them ? XML is an extensible markup language of which XHTML is a variant designed to alleviate the problems associated with HTML. XSLT, on the other hand, is a transformation language used (among other things) to transform XHTML. For example XSLT is used by rapple to transform plain source (X)HTML into more presentable web content. You you will need to write your own XSLT or you can use the samples found in the CVS resources module.
• so rapple is not exactly for the beginner ? that's correct! rapple assumes that you have a working familiarity with XML and in particular with XSLT. rapple might appeal to people who like myself are fustrated with existing HTML based templating technologies and are looking for XML centric tools to create standards based websites. The rapple distribution contains the XSLT used to generate this website to help you get started (see the "etc/" directory in the project tarball.)
• can i get involved ? sure! find about more about becoming involved if you wish to contribute towards development or web design. you can get in touch with me if you have specific interests or comments.

building and installing

• what platforms are supported ? rapple has been tested under Linux (kernel 2.6) and FreeBSD 5.* and is likely to work under *BSD and Solaris but no guarantees can be made ;-) rapple is not supported on windows (but if you are interested in porting then please get in touch).
• i'm getting the following error message when i try to use autotools to build rapple: `automake requires `AM_CONFIG_HEADER', not `AC_CONFIG_HEADER' this is a well-known overlapping issue between automake and autoconf which can be resolved by ensuring that you use automake 1.8 (use of AM_CONFIG_HEADER is deprecated in 1.7) or higher together with autoconf 2.58 or higher.
• configure cannot find library X (e.g. expat) but i know it is installed are you sure that it is installed in a standard location ? use ldconfig to find out more about shared libraries on your system and if you find that a library is missing then you can use the LDFLAGS option to tell your linker where it is. whenever this sort of thing happens it is likely that related includes might also appear to be missing so it is usually a good idea also to set the CFLAGS too e.g.,
  
  ./configure CFLAGS=-I/my/include/loc LDFLAGS="-L/my/lib/loc/ -R/my/lib/loc"
  
  alternatively use the --with-X-lib=DIR and --with-X-headers=DIR (see INSTALL file for further details).
• configure appears to work fine on my *BSD system but when i try make it fails BSD make is not the same as GNU make! try using gmake instead ;)

usage

• i am using sablot and my XSLT stylesheet contains a <xsl:include href="other.xsl" /> element but i get a "'arg:other.xsl' not found" error from rapple - what's wrong ? this is a known issue with the sablotron processor. to get the XSLT include element to work you must provide the "file://" protocol along with the absolute path to the included file (i.e., <xsl:include href="file:///path/to/other.xsl" />). if other.xsl itself has xsl:include elements that refer to files in the same directory then it is not necessary to use the file protocol or state absolute paths (the same is true for XSLT document() function calls).
• when rapple processes PHP files my PHP processor complains about parsing errors near the start of the document this could be due to the presence of the XML declaration (or prolog) at the start of the output:
  <?xml version="1.0" encoding="iso-8859-1" ?>
  to solve this problem instruct your XSLT to omit the declaration using the top level <xsl:output> element
  <xsl:output method="xml" version="1.0" encoding="iso-8859-1" omit-xml-declaration="yes" />
  the version and encoding (and optionally the standalone) attributes reflect those that would be found in the declaration if the omit instruction was absent or set to "no". note that the omit-xml-declaration has no significance if the method attribute is not set to "xml".
• some of my documents include characters (e.g., curly quotes) that get distorted by rapple, how do i stop this happening ? this often happens when the incorrect character encoding is used to achieve effects (e.g. curly quotes) that are not supported by the usual character encodings (e.g., ASCII, ISO-8859-1 etc.) if you are using an editor such as a word processor then it is necessary to set the character encoding to IS0-8859-1 (also known as "Latin-1") before saving the document to HTML.
• i think i have found a bug! what should i do ? first have a look at mailing lists and/or bug reports to see if the bug is already known. only then should raise a bug report. your bug report should be precise enough for the rapple development team to reproduce otherwise it will likely be ignored or rejected. if you think you have a fix then consider send it to the developer's mailing list or becoming a developer yourself!