summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2023-11-12 15:24:33 -0500
committerDavid Thompson <dthompson2@worcester.edu>2023-11-12 15:27:28 -0500
commite558ad0913ed628b105990ab61c341c030244d3a (patch)
tree34c15098bac6bd9872c7acdc961769c9471a566b /doc
parent70eae6e0431ef343886bdfa7538dc6028e294c7e (diff)
doc: Document artifacts, remove deprecated interface sections.
Diffstat (limited to 'doc')
-rw-r--r--doc/haunt.texi153
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