%(included file)
%
% \title Base Configuration Definitions for LPdoc
% 
% \module This file provides the base configuration definitions and
%   documentation for an \apl{lpdoc} settings file.
% 
% \author Manuel Hermenegildo
% \author Jose F. Morales

:- use_module(library(doccfg/doccfg_props)).
:- use_module(engine(stream_basic), [sourcename/1]).

% ----------------------------------------------------------------------------
% Paths 

:- export(filepath/1).
:- pred filepath(Path) => dirpath 
# "It defines the directories where the @tt{.pl}
   files to be documented can be found.

   You also need to specify all the paths containing files which are
   used by the files being documented. For example, the paths to files
   included by an @tt{@@include} command or to figures.".

:- default_def(filepath/1, [(filepath(_) :- fail)]).

:- export(output_name/1).
:- pred output_name(Base) => sourcename
# "It determines the base file name of the main documents generated by
   @apl{lpdoc}.

   By default it is equal to the main file name (root) specified in
   @pred{doc_structure/1}.

   If the main file name ends with @tt{_doc}, then it is equal to the
   name without the @tt{_doc} suffix (see @pred{doc_structure/1}).

   If the @tt{versioned_output} option is specified in
   @pred{doc_mainopts/1}, the bundle version number is appended to the
   output name.".

:- default_def(output_name/1, [(output_name(_) :- fail)]).

:- export(output_dir/1).
:- pred output_dir(Base) => sourcename
# "Output directory. If undefined, uses directory of input".
:- default_def(output_dir/1, [(output_dir(_) :- fail)]).

% ----------------------------------------------------------------------------
% The document structure

:- export(doc_structure/1).
:- pred doc_structure(Term) # "It defines the document structure as a
   tree.

   The tree is defined as a root node with optional children. Nodes
   can be atoms or pairs (@tt{N-Cs}), where @tt{Cs} is a list of
   nodes. The root of the tree is the main file of the manual, i.e.,
   the file which determines the manual's cover page, and first
   chapter. The children files are used as components, i.e., they will
   constitute the subsequent chapters of the manual.

   If the main or any component file name ends with @tt{_doc}, then it
   is treated as documenting the same file name without the @tt{_doc}
   suffix. This is useful for separating the documentation from the
   source file (see 
   @ref{Separating the documentation from the source file}).".

% (no default, must be defined)

% ----------------------------------------------------------------------------
% Processing options for the different files

:- export(doc_mainopts/1).
:- pred doc_mainopts(Option) :: supported_option
# "@var{Option} is a processing option which should be activated when
   processing the main file. 

   It can be set to a series of options which allow more detailed
   control of what is included in the documentation for the main file
   and how (i.e., including bug information @cindex{including or not
   bug info}, versions and patches or only patches @cindex{including
   or not versions, patches}, authors @cindex{including or not
   authors}, changelog @cindex{including or not changelog},
   explanation of modes, @index{one-sided printing} (@index{two-sided}
   is the default), etc.).

   See @pred{option_comment/2} for a description of these options.

   The default values are: @tt{no_bugs}, @tt{no_patches}.".
    
:- default_def(doc_mainopts/1, [doc_mainopts(no_bugs)]).
:- default_def(doc_mainopts/1, [doc_mainopts(no_patches)]).

:- export(doc_compopts/1).
:- pred doc_compopts(Option) :: supported_option
# "@var{Option} is a processing option which should be activated when
   processing the secondary files (all except the main file).

   Currently these options are common to all component files but they
   can be different from @pred{doc_mainopts/1}.

   See @pred{option_comment/2} for a description of these options.

   The default values are: @tt{no_bugs}, @tt{no_patches}.".

:- default_def(doc_compopts/1, [doc_compopts(no_bugs)]).
:- default_def(doc_compopts/1, [doc_compopts(no_patches)]).

% ----------------------------------------------------------------------------
% Default document formats

:- export(docformat/1).
:- pred docformat(Format) => supported_format
   # "Defines the documentation formats to be generated by default.

   If the main file is an @bf{application}, and the @tt{manl} option
   is selected, then @apl{lpdoc} looks for a @pred{usage_message/1}
   fact, which should contain a string as argument, and will use that
   string to document the @index{usage of the application} (i.e., it
   will be used to fill in the @index{synopsis section of the man
   page}).

   See @pred{supported_format/1} for the available formats.

   The default values are: @tt{pdf}, @tt{manl}, @tt{info}, @tt{html}.".

:- default_def(docformat/1, [
    docformat(pdf),
    docformat(manl),
    docformat(info),
    docformat(html)
]).

% ----------------------------------------------------------------------------
% Indices to be generated

:- export(index/1).
:- pred index(Idx) => supported_index
   # "Defines the index sections to be generated by default.

   Selecting @tt{all} generates all the supported indices. However,
   note that this (as well as selecting many indices explicitely)
   exceeds the capacity of most texinfo installations.

   See @pred{index_comment/1} for a description of the indices.

   The default values are: @tt{concept}, @tt{lib}, @tt{pred},
   @tt{prop}, @tt{regtype}, @tt{decl}, @tt{author}, @tt{global}.".

:- default_def(index/1, [
    index(concept),
    index(lib),
    index(pred),
    index(prop),
    index(regtype),
    index(decl),
    index(author),
    % index(cite),
    index(global)
]).

% ----------------------------------------------------------------------------
% References

:- export(bibfile/1).
:- pred bibfile(F) => filename
# "It determines a list of @index{.bib files} (one
   file per path), i.e., files containing @index{bibliographic
   entries} in @apl{bibtex} @cindex{bibtex} format.

   This is only relevant if you are @concept{using citations} in the
   text (using the @concept{@@cite command}). In that case those will
   be the files in which the citations will be searched for. All the
   references will appear together in a @em{References} appendix at
   the end of the manual.

   If you are not using citations, then select the @tt{no_biblio}
   option on the main file, which will prevent an empty 'References'
   appendix from appearing in the manual.".

:- default_def(bibfile/1, [(bibfile(_) :- fail)]).

% ----------------------------------------------------------------------------
% Other settings

:- export(startpage/1).
:- pred startpage(PageNumber) => int
# "Page number of the first page of the manual.

   @cindex{page numbering, changing}

   Setting this to a different value allows changing the page number
   of the first page of the manual. This can be useful if the manual
   is to be included in a larger document or set of manuals.
   Typically, this should be an @em{odd} number.

   The default value is 1.".

:- default_def(startpage/1, [
    startpage(1)
]).

:- export(papertype/1).
:- pred papertype(PageNumber) => supported_papertype
# "Type of paper/format for printable outputs (e.g., @tt{pdf}).

@cindex{page size, changing}
@cindex{page style, changing}

   The currently supported outputs (most of them inherited from
   @apl{texinfo}) are:

   @begin{description}
 
   @item{@tt{afourpaper}} 
 
      The default, usable for printing on @index{A4 paper}. Rather busy, but
      saves trees.
 
   @item{@tt{afourwide}} 
 
      This one crams even more stuff than @tt{afourpaper} on an A4
      page. Useful for generating manuals in the least amount of space.
      It saves more trees.
 
   @item{@tt{afourlatex}} 
 
      This one is a little less compressed than @tt{afourpaper}.
 
   @item{@tt{smallbook}} 
 
      Small pages, like in a handbook. 
 
   @item{@tt{letterpaper}} 
 
      For printing on American @index{letter size paper}.
 
   @item{@tt{afourthesis}} 
 
      A @index{thesis-like style} (i.e., double spaced, wide margins
      etc.). Useful -- for inserting @apl{lpdoc} output as appendices 
      of a thesis or similar document. It does not save trees. 
 
   @end{description}

   See also the @tt{onesided} option for the main
   file.

   The default value is: @tt{afourpaper}.".

:- default_def(papertype/1, [
    papertype(afourpaper)
]).

:- export(libtexinfo/1).
:- pred libtexinfo/1 => yesno
# "If set to yes the @file{texinfo.tex} file that comes with the
   lpdoc distribution will be used when generating manuals in
   formats such as @tt{dvi} and @tt{ps}. Otherwise, the texinfo file
   that comes with your @apl{tex} installation will be used. It is
   recommended that you leave this set to @tt{'yes'}.".
:- default_def(libtexinfo/1, [
    libtexinfo(yes)
]).

:- export(comment_version/1).
:- pred comment_version/1 => yesno
# "The source files contain version information. If not
   specified lpdoc will assume the opposite".
:- default_def(comment_version/1, [
    comment_version(no)
]).

:- export(allow_markdown/1).
:- pred allow_markdown/1 => yesno
# "Allow LPdoc-flavored markdown in docstrings".
:- default_def(allow_markdown/1, [
    allow_markdown(yes)
]).

:- export(allow_runnable/1).
:- pred allow_runnable/1 => yesno
# "Allow runnable code blocks (Ciao Playground)".
:- default_def(allow_runnable/1, [
    allow_runnable(no)
]).

:- export(syntax_highlight/1).
:- pred syntax_highlight/1 => yesno
# "Syntax highlight code blocks (only for HTML backend)".
:- default_def(syntax_highlight/1, [
    syntax_highlight(yes)
]).

:- export(verbosity/1).
:- pred verbosity/1 => verbosity_t
# "Level of verbosity of messages. @tt{quiet} means no messages
  printed, @tt{progress} means standard messages, and @tt{full} means
  more detailed messages. See @pred{verbosity_t/1}.  Default is
  @tt{progress}.".
:- default_def(verbosity/1, [
    verbosity(progress)
]).

:- export(warning_level/1).
:- pred warning_level/1 => warning_level_t
# "Warning reporting level. @tt{none} means only error messages are
   printed, @tt{normal} means errors and warnings, @tt{all} means also
   notes.  See @pred{autodoc_message_t/1}.".
:- default_def(warning_level/1, [
    warning_level(normal)
]).

% ---------------------------------------------------------------------------
% Settings for texinfo backend

:- export(autogen_warning/1).
:- pred autogen_warning/1 => yesno
# "Include an @em{automatically generated} notice inside the output text.".
:- default_def(autogen_warning/1, [
    autogen_warning(no)
]).

% ---------------------------------------------------------------------------
% Settings for HTML backend

:- export(html_layout/1).
:- pred html_layout/1 => term
# "Layout for html output.".
:- default_def(html_layout/1, [(html_layout(_) :- fail)]).

:- export(htmlurl/1).
:- pred htmlurl/1 => term
# "Deploy URL for html output".
:- default_def(htmlurl/1, [(htmlurl(_) :- fail)]).

% TODO: Add target subdir (e.g., foocss => css/)
:- export(html_asset/1).
:- pred html_asset/1 => dirpath
# "Directory with additional files for HTML backend".
:- default_def(html_asset/1, [(html_asset(_) :- fail)]).

:- export(tmplpath/1).
:- pred tmplpath/1 => dirpath
# "Directory for HTML templates".
:- default_def(tmplpath/1, [(tmplpath(_) :- fail)]).

% ----------------------------------------------------------------------------
% Documentation modules (doc_module) for extensions

% TODO: This is experimental.
% TODO: Make it local to each module (not global in the doccfg file).
:- export(load_doc_module/1).
:- pred load_doc_module(F) => term
# "Documentation module (@tt{doc_module}) for extensions (see
  @lib{doc_module}).".
:- default_def(load_doc_module/1, [(load_doc_module(_) :- fail)]).

