doc: Document artifacts, remove deprecated interface sections.

2 files changed, 72 insertions, 83 deletions

diff --git a/TODO.org b/TODO.org
index b6ec358..f4b5004 100644
--- a/TODO.org
+++ b/TODO.org
@@ -28,7 +28,7 @@ posts. Some people want a hierarchy based on date, for example.
 ** Add blog theme example to manual
 ** DONE Remove website directory
 That is no longer used for the actual website
-** Add docs for artifacts
+** DONE Add docs for artifacts
 ** Allow collection pages to live in a different directory than posts.
 ** Feature request: Auto-reload pages when --watch detects changes
 ** External command processing
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