diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/haunt.texi | 153 |
1 files changed, 71 insertions, 82 deletions
diff --git a/doc/haunt.texi b/doc/haunt.texi index d1d7044..96dc134 100644 --- a/doc/haunt.texi +++ b/doc/haunt.texi @@ -408,10 +408,10 @@ For details on how to configure publishers, @pxref{Publishers}. * Sites:: Description of the site and how to build it. * Posts:: Articles, prose, blog posts, etc. * Readers:: Post interpreters. -* Pages:: HTML/XML pages. -* Assets:: Images, stylesheets, etc. * Builders:: Web page builders. * Publishers:: How to publish your site. +* Artifacts:: The build outputs that form a website. +* Assets:: Images, stylesheets, etc. @end menu Haunt is a fully-programmable system composed of several Guile Scheme @@ -790,83 +790,6 @@ specification of Markdown, learn more about CommomMark @end defvr -@node Pages -@section Pages - -@example -(use-modules (haunt page)) -@end example - -Page objects represent files that have yet to be written to disk. -Their contents may be any arbitrary object that their writer procedure -knows how to serialize. In practice, pages are almost always written -to disk as HTML or XML. - -@deffn {Procedure} make-page @var{file-name} @var{contents} @var{writer} -Create a new page object. The string @var{file-name} specifies where -the page should be written to in the file system. The procedure -@var{writer} is responsible for serializing @var{contents}. -@end deffn - -@deffn {Procedure} page? @var{object} -Return @code{#t} if @var{object} is a page object. -@end deffn - -@deffn {Procedure} page-file-name @var{page} -Return the file name string for @var{page}. -@end deffn - -@deffn {Procedure} page-contents @var{page} -Return the contents of @var{page}. -@end deffn - -@deffn {Procedure} page-writer @var{page} -Return the writer procedure @var{page}. -@end deffn - -@deffn {Procedure} write-page @var{page} @var{output-directory} -Write @var{page} to @var{output-directory}. -@end deffn - -@node Assets -@section Assets - -@example -(use-modules (haunt asset)) -@end example - -Assets represent files on disk that should be copied verbatim to a -site's output directory. Common types of assets include CSS, -JavaScript, images, and fonts. - -@deffn {Procedure} make-asset @var{source} @var{target} -Create a new asset object. The @var{source} and @var{target} -arguments are file names that are relative to a site source and target -directory, respectively (@pxref{Sites}). -@end deffn - -@deffn {Procedure} asset? @var{object} -Return @code{#t} if @var{object} is an asset object. -@end deffn - -@deffn {Procedure} asset-source @var{asset} -Return the source file name for @var{asset}. -@end deffn - -@deffn {Procedure} asset-target @var{asset} -Return the target file name for @var{asset}. -@end deffn - -@deffn {Procedure} install-asset @var{asset} @var{prefix} -Install the source file of @var{asset} into the target directory -within @var{prefix}. -@end deffn - -@deffn {Procedure} directory-assets @var{directory} @var{keep?} @var{dest} -Create a list of asset objects to be stored within @var{dest} for all -files in @var{directory} that match @var{keep?}, recursively. -@end deffn - @node Builders @section Builders @@ -876,9 +799,9 @@ files in @var{directory} that match @var{keep?}, recursively. * Atom:: Atom feeds. @end menu -Builders are procedures that return one or more page objects -(@pxref{Pages}) when applied. A builder accepts two arguments: A site -(@pxref{Sites}) and a list of posts (@pxref{Posts}). +Builders are procedures that return one or more artifacts +(@pxref{Artifacts}) when applied. A builder accepts two arguments: A +site (@pxref{Sites}) and a list of posts (@pxref{Posts}). Haunt comes with a few convenient builders to help users who want to create a simple blog with an Atom feed. @@ -1093,6 +1016,72 @@ and/or @var{tar} overrides the default @command{hut} and @command{tar} executables used. @end deffn +@node Artifacts +@section Artifacts + +@example +(use-modules (haunt artifact)) +@end example + +Artifacts are objects that represent the output of a build. A +collection of artifacts forms a complete website. Artifacts are quite +simple: They contain a file name string that specifies where the +artifact belongs in the build output directory, and a writer procedure +that populates that file with data. + +For example, making an artifact that writes ``Hello, world!'' to +@file{/hello.txt} would look like this: + +@example +(make-artifact "/hello.txt" + (lambda (output) + (call-with-output-file output + (lambda (port) + (display "Hello, world!\n" port))))) +@end example + +Previous versions of Haunt made a distinction between pages, whose +content is defined algorithmically, and assets, whose content is +copied verbatim from an input file such as an image. The artifact +data type is a unifying primitive that replaces both pages and assets. + +Artifacts that require serializing some input, such as SXML, should +use @code{serialize-artifact}. Artifacts that make a verbatim copy of +an input file should use @code{verbatim-artifact}. Unless you are +implementing a custom builder, it's unlikely that these procedures +will be need to used directly. + +@deffn {Procedure} serialized-artifact destination obj serialize +Return a new artifact whose writer serializes @var{obj} using the +procedure @var{serialize} to the @var{destination} in the build output +directory. +@end deffn + +@deffn {Procedure} verbatim-artifact source destination +Return a new artifact that copies the file @var{source} verbatim to +@var{destination} within the build output directory. +@end deffn + +@node Assets +@section Assets + +@example +(use-modules (haunt asset)) +@end example + +Assets represent files on disk that should be copied verbatim to a +site's output directory. Common types of assets include CSS, +JavaScript, images, and fonts. It is often the case that there are +entire directories full of static assets to copy over, thus there is a +convenient @code{directory-assets} procedure. However, it's unlikely +that this procedure needs to be used directly. See @pxref{Static +Assets} for a convenient builder. + +@deffn {Procedure} directory-assets @var{directory} @var{keep?} @var{dest} +Create a list of asset objects to be stored within @var{dest} for all +files in @var{directory} that match @var{keep?}, recursively. +@end deffn + @node Contributing @chapter Contributing |