You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2 lines
27 KiB
HTML
2 lines
27 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>File formats</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="racket.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-racket.css" title="default"/><script type="text/javascript" src="scribble-common.js"></script><script type="text/javascript" src="manual-racket.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="file:///Users/mb/git/pollen/scribblings/formats.html" class="tocviewselflink" data-pltdoc="x">File formats</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28part._.Source_formats%29" class="tocviewlink" data-pltdoc="x">Source formats</a></td></tr><tr><td align="right">2 </td><td><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28part._.Utility_formats%29" class="tocviewlink" data-pltdoc="x">Utility formats</a></td></tr><tr><td align="right">3 </td><td><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28part._.Escaping_output-file_extensions_within_source-file_names%29" class="tocviewlink" data-pltdoc="x">Escaping output-<wbr></wbr>file extensions within source-<wbr></wbr>file names</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber"></span><a href="#%28part._.File_formats%29" class="tocsubseclink" data-pltdoc="x">File formats</a></td></tr><tr><td><span class="tocsublinknumber">1<tt> </tt></span><a href="#%28part._.Source_formats%29" class="tocsubseclink" data-pltdoc="x">Source formats</a></td></tr><tr><td><span class="tocsublinknumber">1.1<tt> </tt></span><a href="#%28part._.Command_syntax_using__%29" class="tocsubseclink" data-pltdoc="x">Command syntax using ◊</a></td></tr><tr><td><span class="tocsublinknumber">1.2<tt> </tt></span><a href="#%28part._.Any_command_is_valid%29" class="tocsubseclink" data-pltdoc="x">Any command is valid</a></td></tr><tr><td><span class="tocsublinknumber">1.3<tt> </tt></span><a href="#%28part._.Standard_exports%29" class="tocsubseclink" data-pltdoc="x">Standard exports</a></td></tr><tr><td><span class="tocsublinknumber">1.4<tt> </tt></span><a href="#%28part._.Custom_exports%29" class="tocsubseclink" data-pltdoc="x">Custom exports</a></td></tr><tr><td><span class="tocsublinknumber">1.5<tt> </tt></span><a href="#%28part._.The__pollen_rkt__file%29" class="tocsubseclink" data-pltdoc="x">The <span class="stt">"pollen.rkt"</span> file</a></td></tr><tr><td><span class="tocsublinknumber">1.6<tt> </tt></span><a href="#%28part._.Preprocessor___pp_extension_%29" class="tocsubseclink" data-pltdoc="x">Preprocessor (.pp extension)</a></td></tr><tr><td><span class="tocsublinknumber">1.7<tt> </tt></span><a href="#%28part._.Markdown___pmd_extension_%29" class="tocsubseclink" data-pltdoc="x">Markdown (.pmd extension)</a></td></tr><tr><td><span class="tocsublinknumber">1.8<tt> </tt></span><a href="#%28part._.Markup___pm_extension_%29" class="tocsubseclink" data-pltdoc="x">Markup (.pm extension)</a></td></tr><tr><td><span class="tocsublinknumber">1.9<tt> </tt></span><a href="#%28part._.Pagetree____ptree_extension_%29" class="tocsubseclink" data-pltdoc="x">Pagetree (.ptree extension)</a></td></tr><tr><td><span class="tocsublinknumber">2<tt> </tt></span><a href="#%28part._.Utility_formats%29" class="tocsubseclink" data-pltdoc="x">Utility formats</a></td></tr><tr><td><span class="tocsublinknumber">2.1<tt> </tt></span><a href="#%28part._.Scribble____scrbl_extension_%29" class="tocsubseclink" data-pltdoc="x">Scribble (.scrbl extension)</a></td></tr><tr><td><span class="tocsublinknumber">2.2<tt> </tt></span><a href="#%28part._.Null___p_extension_%29" class="tocsubseclink" data-pltdoc="x">Null (.p extension)</a></td></tr><tr><td><span class="tocsublinknumber">3<tt> </tt></span><a href="#%28part._.Escaping_output-file_extensions_within_source-file_names%29" class="tocsubseclink" data-pltdoc="x">Escaping output-<wbr></wbr>file extensions within source-<wbr></wbr>file names</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="versionNoNav">6.2.900.15</span></div><h2><a name="(part._.File_formats)"></a>File formats</h2><h3>1<tt> </tt><a name="(part._.Source_formats)"></a><a name="(mod-path._pollen/pre)"></a><a name="(mod-path._pollen/markdown)"></a><a name="(mod-path._pollen/markup)"></a><a name="(mod-path._pollen/ptree)"></a>Source formats</h3><p><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fpre%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/pre</span></a></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <span class="stt">pollen</span></span></td></tr><tr><td align="left" colspan="2"><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fmarkdown%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/markdown</span></a></td></tr><tr><td align="left" colspan="2"><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fmarkup%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/markup</span></a></td></tr><tr><td align="left" colspan="2"><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fptree%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/ptree</span></a></td></tr></table></p><p>The Pollen language is divided into variants, or <span style="font-style: italic">dialects</span>, that are tailored to suit each of the core source formats.</p><p>These dialects can be invoked one of two ways: either by invoking a specific dialect in the first line of the file (also known as the <span class="stt">#lang</span> line), or by using the generic <span class="stt">#lang pollen</span> as the first line, and then the correct dialect will be automatically selected based on the source file extension.</p><p>If the <span class="stt">#lang</span> line specifies a dialect different from the one specified by the file extension, the <span class="stt">#lang</span> line will take precedence.</p><p>For ease of use, the behavior of the Pollen language departs from the standard Racket language in several ways. The differences are noted below.</p><h4>1.1<tt> </tt><a name="(part._.Command_syntax_using__)"></a>Command syntax using ◊</h4><p>Commands must start with the special lozenge character <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊</span><span class="hspace"></span></span>. Other material is interpreted as plain text. See <font class="badlink">(part "pollen-command-syntax")</font> for more.</p><p><span style="font-weight: bold">How is this different from Racket?</span> In Racket, everything is a command, and plain text must be quoted.</p><h4>1.2<tt> </tt><a name="(part._.Any_command_is_valid)"></a>Any command is valid</h4><p>There are no undefined commands in Pollen. If a command has not already been defined, it’s treated as a tag function. See <font class="badlink">(part "pollen-command-syntax")</font> for more.</p><p><span style="font-weight: bold">How is this different from Racket?</span> In Racket, if you try to treat an identifier as a function before defining it with <span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span>, you’ll get an error.</p><h4>1.3<tt> </tt><a name="(part._.Standard_exports)"></a>Standard exports</h4><p>By default, every Pollen source file exports two identifiers, which you can access by using the source file with <span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span>:</p><p>The main export, <span class="RktSym">doc</span>, contains the output of the file. The type of output depends on the source format (documented below).</p><p>The second export, <span class="RktSym">metas</span>, is a hashtable of key–value pairs with extra information that is extracted from the source. These <span class="RktSym">metas</span> will always contain the key <span class="RktVal">'</span><span class="RktVal">here-path</span>, which returns a string representation of the full path to the source file. Beyond that, the only <span class="RktSym">metas</span> are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas).</p><p>Pollen source files also make the <span class="RktSym">metas</span> hashtable available through a submodule, also called <span class="RktSym">metas</span>. So rather than importing a source file with <span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="stt"> </span><span class="RktVal">"source.html.pm"</span><span class="RktPn">)</span>, you would <span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">submod</span></span></span><span class="stt"> </span><span class="RktVal">"source.html.pm"</span><span class="stt"> </span><span class="RktSym">metas</span><span class="RktPn">)</span><span class="RktPn">)</span>. Accessing the metas this way avoids fully compiling the source file, and thus will usually be faster.</p><p>The names <span class="RktSym">doc</span> and <span class="RktSym">metas</span> can be changed for a project by overriding <span class="RktSym"><span class="badlink"><span class="RktValLink">world:main-export</span></span></span> and <span class="RktSym"><span class="badlink"><span class="RktValLink">world:meta-export</span></span></span>.</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>The Pollen rendering system relies on these two identifiers, but otherwise doesn’t care how they’re generated. Meaning, the code inside your Pollen source file could be <span class="stt">#lang racket</span> or <span class="stt">#lang whatever</span>. As long as you manually <span class="RktSym"><span class="badlink"><span class="RktValLink">provide</span></span></span> those two identifiers and follow the usual file-naming convention, your source file will be usable.</p></blockquote></blockquote></blockquote><p><span style="font-weight: bold">How is this different from Racket?</span> In Racket, you must explicitly <span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span> and then <span class="RktSym"><span class="badlink"><span class="RktValLink">provide</span></span></span> any values you want to export.</p><h4>1.4<tt> </tt><a name="(part._.Custom_exports)"></a>Custom exports</h4><p>Any value or function that is defined within the source file using <span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span> is automatically exported.</p><p><span style="font-weight: bold">How is this different from Racket?</span> In Racket, you must explicitly <span class="RktSym"><span class="badlink"><span class="RktValLink">provide</span></span></span> any values you want to export. Unlike Racket, every Pollen source file impliedly uses <span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">provide</span></span></span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">all-defined-out</span></span></span><span class="RktPn">)</span><span class="RktPn">)</span>.</p><h4>1.5<tt> </tt><a name="(part._.The__pollen_rkt__file)"></a>The <span class="stt">"pollen.rkt"</span> file</h4><p>If a file called <span class="stt">"pollen.rkt"</span> exists in the same directory with a source file, or in a parent directory of that source file, it’s automatically imported when the source file is compiled.</p><p><span style="font-weight: bold">How is this different from Racket?</span> In Racket, you must explicitly import files using <span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span>.</p><h4>1.6<tt> </tt><a name="(part._.Preprocessor___pp_extension_)"></a>Preprocessor (.pp extension)</h4><p>Invoke the preprocessor dialect by using <font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fpre%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/pre</span></a><span class="RktMeta"></span> as the first line of your source file, or by using <font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span> with a file extension of <span class="RktSym">.pp</span><span class="RktMeta"></span>. These forms are equivalent:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"sample.css.pp"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"sample.css"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fpre%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/pre</span></a></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><p>When no dialect is explicitly specified by either the <span class="stt">#lang</span> line or the file extension, Pollen will default to using the preprocessor dialect. For instance, this file will be treated as preprocessor source:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"test.yyz"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><p>Of course, you’re better off specifying the preprocessor dialect explicitly rather than relying on this default behavior.</p><p>The output of the preprocessor dialect, provided by <span class="RktVal">'</span><span class="RktVal">doc</span>, is plain text.</p><h4>1.7<tt> </tt><a name="(part._.Markdown___pmd_extension_)"></a>Markdown (.pmd extension)</h4><p>Invoke the Markdown dialect by using <font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fmarkdown%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/markdown</span></a><span class="RktMeta"></span> as the first line of your source file, or by using <font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span> with a file extension of <span class="RktSym">.pmd</span><span class="RktMeta"></span>. These forms are equivalent:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"sample.txt.pmd"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"sample.txt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fmarkdown%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/markdown</span></a></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><p>The output of the Markdown dialect, provided by <span class="RktSym">doc</span>, is a tagged X-expression.</p><h4>1.8<tt> </tt><a name="(part._.Markup___pm_extension_)"></a>Markup (.pm extension)</h4><p>Invoke the Pollen markup dialect by using <font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fmarkup%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/markup</span></a><span class="RktMeta"></span> as the first line of your source file, or by using <font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span> with a file extension of <span class="RktSym">.pm</span><span class="RktMeta"></span>. These forms are equivalent:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"about.html.pm"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"about.html"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fmarkup%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/markup</span></a></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><p>The output of the Pollen markup dialect, provided by <span class="RktSym">doc</span>, is a tagged X-expression.</p><h4>1.9<tt> </tt><a name="(part._.Pagetree____ptree_extension_)"></a>Pagetree (.ptree extension)</h4><p>Invoke the pagetree dialect by using <font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fptree%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/ptree</span></a><span class="RktMeta"></span> as the first line of your source file, or by using <font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span> with a file extension of <span class="RktSym">.ptree</span><span class="RktMeta"></span>. These forms are equivalent:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"main.ptree"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"main.rkt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/formats.html#%28mod-path._pollen%2Fptree%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/ptree</span></a></td></tr><tr><td><span class="RktVar">...source...</span></td></tr></table></blockquote></blockquote></blockquote><p>The output of the pagetree dialect, provided by <span class="RktSym">doc</span>, is a <span class="RktSym"><span class="badlink"><span class="RktValLink">pagetree?</span></span></span> that is checked for correctness using <span class="RktSym"><span class="badlink"><span class="RktValLink">validate-pagetree</span></span></span>.</p><h3>2<tt> </tt><a name="(part._.Utility_formats)"></a>Utility formats</h3><p>These aren’t source formats because they don’t contain a <span class="stt">#lang pollen</span> line. But for convenience, they get special handling by the Pollen project server.</p><h4>2.1<tt> </tt><a name="(part._.Scribble____scrbl_extension_)"></a>Scribble (.scrbl extension)</h4><p>Scribble files are recognized by the project server and can be compiled and previewed in single-page mode.</p><h4>2.2<tt> </tt><a name="(part._.Null___p_extension_)"></a>Null (.p extension)</h4><p>Files with the null extension are simply rendered as a copy of the file without the extension, so <span class="stt">"index.html.p"</span> becomes <span class="stt">"index.html"</span>.</p><p>This can be useful you’re managing your project with git. Most likely you’ll want to ignore <span class="stt">"*.html"</span> and other file types that are frequently regenerated by the project server. But if you have isolated static files — for instance, a <span class="stt">"index.html"</span> that doesn’t have source associated with it — they’ll be ignored too. You can cure this problem by appending the null extension to these static files, so they’ll be tracked in your source system without actually being source files.</p><h3>3<tt> </tt><a name="(part._.Escaping_output-file_extensions_within_source-file_names)"></a>Escaping output-file extensions within source-file names</h3><p>Pollen relies extensively on the convention of naming source files by adding a source extension to an output-file name. So the Pollen markup source for <span class="stt">"index.html"</span> would be <span class="stt">"index.html.pm"</span>.</p><p>This convention occasionally flummoxes other programs that assume a file can only have one extension. If you run into such a situation, you can <span style="font-style: italic">escape</span> the output-file extension using the <span class="RktSym"><span class="badlink"><span class="RktValLink">world:extension-escape-char</span></span></span>, which defaults to the underscore <span class="RktInBG"><span class="hspace"></span><span class="RktIn">_</span><span class="hspace"></span></span>.</p><p>So instead of <span class="stt">"index.html.pm"</span>, your source-file name would be <span class="stt">"index_html.pm"</span>. When this source file is rendered, it will automatically be converted into <span class="stt">"index.html"</span> (meaning, the escaped extension will be converted into a normal file extension).</p><p>This alternative-naming scheme is automatically enabled in every project. You can also set the escape character on a per-project basis (see <span class="RktSym"><span class="badlink"><span class="RktValLink">world:current-extension-escape-char</span></span></span>). Pollen will let you choose any character, but of course it would be unwise to pick one with special meaning in your filesystem (for instance, <span class="RktInBG"><span class="hspace"></span><span class="RktIn">/</span><span class="hspace"></span></span>).</p></div></div><div id="contextindicator"> </div></body></html> |