% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(doc_files): Create stand-alone documentation files}

\label{sec:docfiles}

\begin{tags}
    \tag{To be done}
Generate a predicate index?
\end{tags}

Create stand-alone documentation from a bundle of source-files. Typical
use of the PlDoc package is to run it as a web-server from the project
in progress, providing search and guaranteed consistency with the loaded
version. Creating stand-alone files as provided by this file can be
useful for printing or distribution.\vspace{0.7cm}

\begin{description}
    \predicate{doc_save}{2}{+FileOrDir, +Options}
Save documentation for \arg{FileOrDir} to \verb$file(s)$. \arg{Options} include

\begin{description}
    \termitem{format}{+Format}
Currently only supports \const{html}.
    \termitem{doc_root}{+Dir}
Save output to the given directory. Default is to save
the documentation for a file in the same directory as
the file and for a directory in a subdirectory \const{doc}.
    \termitem{title}{+Title}
\arg{Title} is an atom that provides the HTML title of the
main (index) page. Only meaningful when generating
documentation for a directory.
    \termitem{man_server}{+RootURL}
Root of a manual server used for references to built-in
predicates. Default is
\verb$http://www.swi-prolog.org/pldoc/$
    \termitem{index_file}{+Base}
Filename for directory indices. Default is \const{index}.
    \termitem{if}{Condition}
What to do with files in a directory. \const{loaded} (default)
only documents files loaded into the Prolog image. \const{true}
documents all files.
    \termitem{recursive}{+Bool}
If \const{true}, recurse into subdirectories.
    \termitem{css}{+Mode}
If \const{copy}, copy the CSS file to created directories.
Using \const{inline}, include the CSS file into the created
files. Currently, only the default \const{copy} is supported.
\end{description}

The typical use-case is to document the Prolog files that belong
to a project in the current directory. To do this load the
Prolog files and run the goal below. This creates a
sub-directory \const{doc} with an index file \verb$index.html$. It
replicates the directory structure of the source directory,
creating an HTML file for each Prolog file and an index file for
each sub-directory. A copy of the required CSS and image
resources is copied to the \const{doc} directory.

\begin{code}
?- doc_save(., [recursive(true)]).
\end{code}

\end{description}