/*  Part of SWI-Prolog

    Author:        Jan Wielemaker
    E-mail:        J.Wielemaker@vu.nl
    WWW:           http://www.swi-prolog.org
    Copyright (c)  2007-2015, University of Amsterdam
                              VU University Amsterdam
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in
       the documentation and/or other materials provided with the
       distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.
*/

:- module(pldoc_latex,
          [ doc_latex/3,                % +Items, +OutFile, +Options
            latex_for_file/3,           % +FileSpec, +Out, +Options
            latex_for_wiki_file/3,      % +FileSpec, +Out, +Options
            latex_for_predicates/3      % +PI, +Out, +Options
          ]).
:- use_module(library(pldoc)).
:- use_module(library(readutil)).
:- use_module(library(error)).
:- use_module(library(apply)).
:- use_module(library(option)).
:- use_module(library(lists)).
:- use_module(library(debug)).
:- use_module(pldoc(doc_wiki)).
:- use_module(pldoc(doc_process)).
:- use_module(pldoc(doc_modes)).
:- use_module(library(pairs), [pairs_values/2]).
:- use_module(library(prolog_source), [file_name_on_path/2]).
:- use_module(library(prolog_xref), [xref_hook/1]).
:- use_module(pldoc(doc_html),          % we cannot import all as the
              [ doc_file_objects/5,     % \commands have the same name
                unquote_filespec/2,
                doc_tag_title/2,
                existing_linked_file/2,
                pred_anchor_name/3,
                private/2,
                (multifile)/2,
                is_pi/1,
                is_op_type/2
              ]).

/** <module> PlDoc LaTeX backend

This  module  translates  the  Herbrand   term  from  the  documentation
extracting module doc_wiki.pl into a  LaTeX   document  for  us with the
pl.sty LaTeX style file. The function of  this module is very similar to
doc_html.pl, providing the HTML backend,  and the implementation follows
the same paradigm. The module can

        * Generate LaTeX documentation for a Prolog file, both for
        printing and embedding in a larger document using
        latex_for_file/3.

        * Generate LaTeX from a Wiki file using latex_for_wiki_file/3

        * Generate LaTeX for a single predicate or a list of predicates
        for embedding in a document using latex_for_predicates/3.

@tbd See TODO
@author Jan Wielemaker
*/

:- predicate_options(doc_latex/3, 3,
                     [ stand_alone(boolean),
                       public_only(boolean),
                       section_level(oneof([section,subsection,subsubsection])),
                       summary(atom)
                     ]).
:- predicate_options(latex_for_file/3, 3,
                     [ stand_alone(boolean),
                       public_only(boolean),
                       section_level(oneof([section,subsection,subsubsection]))
                     ]).
:- predicate_options(latex_for_predicates/3, 3,
                     [                          % no options
                     ]).
:- predicate_options(latex_for_wiki_file/3, 3,
                     [ stand_alone(boolean),
                       public_only(boolean),
                       section_level(oneof([section,subsection,subsubsection]))
                     ]).


:- thread_local
    options/1,
    documented/1.

current_options(Options) :-
    options(Current),
    !,
    Options = Current.
current_options([]).

%!  doc_latex(+Spec, +OutFile, +Options) is det.
%
%   Process one or  more  objects,  writing   the  LaTeX  output  to
%   OutFile.  Spec is one of:
%
%     - Name/Arity
%       Generate documentation for predicate
%     - Name//Arity
%       Generate documentation for DCG rule
%     - File
%       If File is a prolog file (as defined by
%       user:prolog_file_type/2), process using
%       latex_for_file/3, otherwise process using
%       latex_for_wiki_file/3.
%
%   Typically Spec is either a  list  of   filenames  or  a  list of
%   predicate indicators.   Defined options are:
%
%     - stand_alone(+Bool)
%       If =true= (default), create a document that can be run
%       through LaTeX.  If =false=, produce a document to be
%       included in another LaTeX document.
%     - public_only(+Bool)
%       If =true= (default), only emit documentation for
%       exported predicates.
%     - section_level(+Level)
%       Outermost section level produced. Level is the
%       name of a LaTeX section command.  Default is =section=.
%     - summary(+File)
%       Write summary declarations to the named File.
%     - modules(+List)
%       If [[Name/Arity]] needs to be resolved, search for the
%       predicates in the given modules.
%     - module(+Module)
%       Same as modules([Module]).

doc_latex(Spec, OutFile, Options) :-
    load_urldefs,
    merge_options(Options,
                  [ include_reexported(true)
                  ],
                  Options1),
    retractall(documented(_)),
    setup_call_cleanup(
        asserta(options(Options), Ref),
        phrase(process_items(Spec, [body], Options1), Tokens),
        erase(Ref)),
    setup_call_cleanup(
        open(OutFile, write, Out),
        print_latex(Out, Tokens, Options1),
        close(Out)),
    latex_summary(Options).

process_items([], Mode, _) -->
    !,
    pop_mode(body, Mode, _).
process_items([H|T], Mode, Options) -->
    process_items(H, Mode, Mode1, Options),
    process_items(T, Mode1, Options).
process_items(Spec, Mode, Options) -->
    {Mode = [Mode0|_]},
    process_items(Spec, Mode, Mode1, Options),
    pop_mode(Mode0, Mode1, _).

process_items(PI, Mode0, Mode, Options) -->
    { is_pi(PI) },
    !,
    need_mode(description, Mode0, Mode),
    latex_tokens_for_predicates(PI, Options).
process_items(FileSpec, Mode0, Mode, Options) -->
    {   (   absolute_file_name(FileSpec,
                               [ file_type(prolog),
                                 access(read),
                                 file_errors(fail)
                               ],
                               File)
        ->  true
        ;   absolute_file_name(FileSpec,
                               [ access(read)
                               ],
                               File)
        ),
        file_name_extension(_Base, Ext, File)
    },
    need_mode(body, Mode0, Mode),
    (   { user:prolog_file_type(Ext, prolog) }
    ->  latex_tokens_for_file(File, Options)
    ;   latex_tokens_for_wiki_file(File, Options)
    ).


%!  latex_for_file(+File, +Out, +Options) is det.
%
%   Generate a LaTeX description of all commented predicates in
%   File, writing the LaTeX text to the stream Out. Supports
%   the options =stand_alone=, =public_only= and =section_level=.
%   See doc_latex/3 for a description of the options.

latex_for_file(FileSpec, Out, Options) :-
    load_urldefs,
    phrase(latex_tokens_for_file(FileSpec, Options), Tokens),
    print_latex(Out, Tokens, Options).


%!  latex_tokens_for_file(+FileSpec, +Options)//

latex_tokens_for_file(FileSpec, Options, Tokens, Tail) :-
    absolute_file_name(FileSpec,
                       [ file_type(prolog),
                         access(read)
                       ],
                       File),
    doc_file_objects(FileSpec, File, Objects, FileOptions, Options),
    asserta(options(Options), Ref),
    call_cleanup(phrase(latex([ \file_header(File, FileOptions)
                              | \objects(Objects, FileOptions)
                              ]),
                        Tokens, Tail),
                 erase(Ref)).


%!  latex_for_wiki_file(+File, +Out, +Options) is det.
%
%   Write a LaTeX translation of  a  Wiki   file  to  the steam Out.
%   Supports   the   options   =stand_alone=,    =public_only=   and
%   =section_level=.  See  doc_latex/3  for  a  description  of  the
%   options.

latex_for_wiki_file(FileSpec, Out, Options) :-
    load_urldefs,
    phrase(latex_tokens_for_wiki_file(FileSpec, Options), Tokens),
    print_latex(Out, Tokens, Options).

latex_tokens_for_wiki_file(FileSpec, Options, Tokens, Tail) :-
    absolute_file_name(FileSpec, File,
                       [ access(read)
                       ]),
    read_file_to_codes(File, String, []),
    b_setval(pldoc_file, File),
    asserta(options(Options), Ref),
    call_cleanup((wiki_codes_to_dom(String, [], DOM),
                  phrase(latex(DOM), Tokens, Tail)
                 ),
                 (nb_delete(pldoc_file),
                  erase(Ref))).


%!  latex_for_predicates(+PI:list, +Out, +Options) is det.
%
%   Generate LaTeX for a list  of   predicate  indicators. This does
%   *not*   produce   the    \begin{description}...\end{description}
%   environment, just a plain list   of \predicate, etc. statements.
%   The current implementation ignores Options.

latex_for_predicates(Spec, Out, Options) :-
    load_urldefs,
    phrase(latex_tokens_for_predicates(Spec, Options), Tokens),
    print_latex(Out, [nl_exact(0)|Tokens], Options).

latex_tokens_for_predicates([], _Options) --> !.
latex_tokens_for_predicates([H|T], Options) -->
    !,
    latex_tokens_for_predicates(H, Options),
    latex_tokens_for_predicates(T, Options).
latex_tokens_for_predicates(PI, Options) -->
    { generic_pi(PI),
      !,
      (   doc_comment(PI, Pos, _Summary, Comment)
      ->  true
      ;   Comment = ''
      )
    },
    object(PI, Pos, Comment, [description], _, Options).
latex_tokens_for_predicates(Spec, Options) -->
    { findall(PI, documented_pi(Spec, PI, Options), List),
      (   List == []
      ->  print_message(warning, pldoc(no_predicates_from(Spec)))
      ;   true
      )
    },
    latex_tokens_for_predicates(List, Options).

documented_pi(Spec, PI, Options) :-
    option(modules(List), Options),
    member(M, List),
    generalise_spec(Spec, PI, M),
    doc_comment(PI, _Pos, _Summary, _Comment),
    !.
documented_pi(Spec, PI, Options) :-
    option(module(M), Options),
    generalise_spec(Spec, PI, M),
    doc_comment(PI, _Pos, _Summary, _Comment),
    !.
documented_pi(Spec, PI, _Options) :-
    generalise_spec(Spec, PI, _),
    doc_comment(PI, _Pos, _Summary, _Comment).

generic_pi(Module:Name/Arity) :-
    atom(Module), atom(Name), integer(Arity),
    !.
generic_pi(Module:Name//Arity) :-
    atom(Module), atom(Name), integer(Arity).

generalise_spec(Name/Arity, M:Name/Arity, M).
generalise_spec(Name//Arity, M:Name//Arity, M).


                 /*******************************
                 *       LATEX PRODUCTION       *
                 *******************************/

:- thread_local
    fragile/0.                      % provided when in fragile mode

latex([]) -->
    !,
    [].
latex(Atomic) -->
    { string(Atomic),
      atom_string(Atom, Atomic),
      sub_atom(Atom, 0, _, 0, 'LaTeX')
    },
    !,
    [ latex('\\LaTeX{}') ].
latex(Atomic) -->                       % can this actually happen?
    { atomic(Atomic),
      !,
      atom_string(Atom, Atomic),
      findall(x, sub_atom(Atom, _, _, _, '\n'), Xs),
      length(Xs, Lines)
    },
    (   {Lines == 0}
    ->  [ Atomic ]
    ;   [ nl(Lines) ]
    ).
latex(List) -->
    latex_special(List, Rest),
    !,
    latex(Rest).
latex(w(Word)) -->
    [ Word ].
latex([H|T]) -->
    !,
    (   latex(H)
    ->  latex(T)
    ;   { print_message(error, latex(failed(H))) },
        latex(T)
    ).

% high level commands
latex(h1(Attrs, Content)) -->
    latex_section(0, Attrs, Content).
latex(h2(Attrs, Content)) -->
    latex_section(1, Attrs, Content).
latex(h3(Attrs, Content)) -->
    latex_section(2, Attrs, Content).
latex(h4(Attrs, Content)) -->
    latex_section(3, Attrs, Content).
latex(p(Content)) -->
    [ nl_exact(2) ],
    latex(Content).
latex(blockquote(Content)) -->
    latex(cmd(begin(quote))),
    latex(Content),
    latex(cmd(end(quote))).
latex(center(Content)) -->
    latex(cmd(begin(center))),
    latex(Content),
    latex(cmd(end(center))).
latex(a(Attrs, Content)) -->
    { attribute(href(HREF), Attrs) },
    (   {HREF == Content}
    ->  latex(cmd(url(url_escape(HREF))))
    ;   { atom_concat(#,Sec,HREF) }
    ->  latex([Content, ' (', cmd(secref(Sec)), ')'])
    ;   latex(cmd(href(url_escape(HREF), Content)))
    ).
latex(br(_)) -->
    latex(latex(\\)).
latex(hr(_)) -->
    latex(cmd(hrule)).
latex(code(CodeList)) -->
    { is_list(CodeList),
      !,
      atomic_list_concat(CodeList, Atom)
    },
    (   {fragile}
    ->  latex(cmd(const(Atom)))
    ;   [ verb(Atom) ]
    ).
latex(code(Code)) -->
    { identifier(Code) },
    !,
    latex(cmd(const(Code))).
latex(code(Code)) -->
    (   {fragile}
    ->  latex(cmd(const(Code)))
    ;   [ verb(Code) ]
    ).
latex(b(Code)) -->
    latex(cmd(textbf(Code))).
latex(strong(Code)) -->
    latex(cmd(textbf(Code))).
latex(i(Code)) -->
    latex(cmd(textit(Code))).
latex(var(Var)) -->
    latex(cmd(arg(Var))).
latex(pre(_Class, Code)) -->
    [ nl_exact(2), code(Code), nl_exact(2) ].
latex(ul(Content)) -->
    { if_short_list(Content, shortlist, itemize, Env) },
    latex(cmd(begin(Env))),
    latex(Content),
    latex(cmd(end(Env))).
latex(ol(Content)) -->
    latex(cmd(begin(enumerate))),
    latex(Content),
    latex(cmd(end(enumerate))).
latex(li(Content)) -->
    latex(cmd(item)),
    latex(Content).
latex(dl(_, Content)) -->
    latex(cmd(begin(description))),
    latex(Content),
    latex(cmd(end(description))).
latex(dd(_, Content)) -->
    latex(Content).
latex(dd(Content)) -->
    latex(Content).
latex(dt(class=term, \term(Text, Term, Bindings))) -->
    termitem(Text, Term, Bindings).
latex(dt(Content)) -->
    latex(cmd(item(opt(Content)))).
latex(table(Attrs, Content)) -->
    latex_table(Attrs, Content).
latex(\Cmd, List, Tail) :-
    call(Cmd, List, Tail).

% low level commands
latex(latex(Text)) -->
    [ latex(Text) ].
latex(cmd(Term)) -->
    { Term =.. [Cmd|Args] },
    indent(Cmd),
    [ cmd(Cmd) ],
    latex_arguments(Args),
    outdent(Cmd).

indent(begin) --> !,           [ nl(2) ].
indent(end) --> !,             [ nl_exact(1) ].
indent(section) --> !,         [ nl(2) ].
indent(subsection) --> !,      [ nl(2) ].
indent(subsubsection) --> !,   [ nl(2) ].
indent(item) --> !,            [ nl(1), indent(4) ].
indent(definition) --> !,      [ nl(1), indent(4) ].
indent(tag) --> !,             [ nl(1), indent(4) ].
indent(termitem) --> !,        [ nl(1), indent(4) ].
indent(prefixtermitem) --> !,  [ nl(1), indent(4) ].
indent(infixtermitem) --> !,   [ nl(1), indent(4) ].
indent(postfixtermitem) --> !, [ nl(1), indent(4) ].
indent(predicate) --> !,       [ nl(1), indent(4) ].
indent(dcg) --> !,             [ nl(1), indent(4) ].
indent(infixop) --> !,         [ nl(1), indent(4) ].
indent(prefixop) --> !,        [ nl(1), indent(4) ].
indent(postfixop) --> !,       [ nl(1), indent(4) ].
indent(predicatesummary) --> !,[ nl(1) ].
indent(dcgsummary) --> !,      [ nl(1) ].
indent(oppredsummary) --> !,   [ nl(1) ].
indent(hline) --> !,           [ nl(1) ].
indent(_) -->                  [].

outdent(begin) --> !,           [ nl_exact(1) ].
outdent(end) --> !,             [ nl(2) ].
outdent(item) --> !,            [ ' ' ].
outdent(tag) --> !,             [ nl(1) ].
outdent(termitem) --> !,        [ nl(1) ].
outdent(prefixtermitem) --> !,  [ nl(1) ].
outdent(infixtermitem) --> !,   [ nl(1) ].
outdent(postfixtermitem) --> !, [ nl(1) ].
outdent(definition) --> !,      [ nl(1) ].
outdent(section) --> !,         [ nl(2) ].
outdent(subsection) --> !,      [ nl(2) ].
outdent(subsubsection) --> !,   [ nl(2) ].
outdent(predicate) --> !,       [ nl(1) ].
outdent(dcg) --> !,             [ nl(1) ].
outdent(infixop) --> !,         [ nl(1) ].
outdent(prefixop) --> !,        [ nl(1) ].
outdent(postfixop) --> !,       [ nl(1) ].
outdent(predicatesummary) --> !,[ nl(1) ].
outdent(dcgsummary) --> !,      [ nl(1) ].
outdent(oppredsummary) --> !,   [ nl(1) ].
outdent(hline) --> !,           [ nl(1) ].
outdent(_) -->                  [].

%!  latex_special(String, Rest)// is semidet.
%
%   Deals with special sequences of symbols.

latex_special(In, Rest) -->
    { url_chars(In, Chars, Rest),
      special(Chars),
      atom_chars(Atom, Chars),
      urldef_name(Atom, Name)
    },
    !,
    latex([cmd(Name), latex('{}')]).

special(Chars) :-
    memberchk(\, Chars),
    !.
special(Chars) :-
    length(Chars, Len),
    Len > 1.

url_chars([H|T0], [H|T], Rest) :-
    urlchar(H),
    !,
    url_chars(T0, T, Rest).
url_chars(L, [], L).


%!  latex_arguments(+Args:list)// is det.
%
%   Write LaTeX command arguments. If  an   argument  is of the form
%   opt(Arg) it is written as  [Arg],   Otherwise  it  is written as
%   {Arg}. Note that opt([]) is omitted. I think no LaTeX command is
%   designed to handle an empty optional argument special.
%
%   During processing the arguments it asserts fragile/0 to allow is
%   taking care of LaTeX fragile   constructs  (i.e. constructs that
%   are not allows inside {...}).

latex_arguments(List, Out, Tail) :-
    asserta(fragile, Ref),
    call_cleanup(fragile_list(List, Out, Tail),
                 erase(Ref)).

fragile_list([]) --> [].
fragile_list([opt([])|T]) -->
    !,
    fragile_list(T).
fragile_list([opt(H)|T]) -->
    !,
    [ '[' ],
    latex_arg(H),
    [ ']' ],
    fragile_list(T).
fragile_list([H|T]) -->
    [ curl(open) ],
    latex_arg(H),
    [ curl(close) ],
    fragile_list(T).

%!  latex_arg(+In)//
%
%   Write a LaTeX argument.  If  we  can,   we  will  use  a defined
%   urldef_name/2.

latex_arg(H) -->
    { atomic(H),
      atom_string(Atom, H),
      urldef_name(Atom, Name)
    },
    !,
    latex(cmd(Name)).
latex_arg(H) -->
    { maplist(atom, H),
      atomic_list_concat(H, Atom),
      urldef_name(Atom, Name)
    },
    !,
    latex(cmd(Name)).
latex_arg(no_escape(Text)) -->
    !,
    [no_escape(Text)].
latex_arg(url_escape(Text)) -->
    !,
    [url_escape(Text)].
latex_arg(H) -->
    latex(H).

attribute(Att, Attrs) :-
    is_list(Attrs),
    !,
    option(Att, Attrs).
attribute(Att, One) :-
    option(Att, [One]).

if_short_list(Content, If, Else, Env) :-
    (   short_list(Content)
    ->  Env = If
    ;   Env = Else
    ).

%!  short_list(+Content) is semidet.
%
%   True if Content describes the content of a dl or ul/ol list
%   where each elemenent has short content.

short_list([]).
short_list([_,dd(Content)|T]) :-
    !,
    short_content(Content),
    short_list(T).
short_list([_,dd(_, Content)|T]) :-
    !,
    short_content(Content),
    short_list(T).
short_list([li(Content)|T]) :-
    short_content(Content),
    short_list(T).

short_content(Content) :-
    phrase(latex(Content), Tokens),
    summed_string_len(Tokens, 0, Len),
    Len < 50.

summed_string_len([], Len, Len).
summed_string_len([H|T], L0, L) :-
    atomic(H),
    !,
    atom_length(H, AL),
    L1 is L0 + AL,
    summed_string_len(T, L1, L).
summed_string_len([_|T], L0, L) :-
    summed_string_len(T, L0, L).


%!  latex_section(+Level, +Attributes, +Content)// is det.
%
%   Emit a LaTeX section,  keeping  track   of  the  desired highest
%   section level.
%
%   @param Level    Desired level, relative to the base-level.  Must
%                   be a non-negative integer.

latex_section(Level, Attrs, Content) -->
    { current_options(Options),
      option(section_level(LaTexSection), Options, section),
      latex_section_level(LaTexSection, BaseLevel),
      FinalLevel is BaseLevel+Level,
      (   latex_section_level(SectionCommand, FinalLevel)
      ->  Term =.. [SectionCommand, Content]
      ;   domain_error(latex_section_level, FinalLevel)
      )
    },
    latex(cmd(Term)),
    section_label(Attrs).

section_label(Attrs) -->
    { is_list(Attrs),
      memberchk(id(Name), Attrs),
      !,
      delete_unsafe_label_chars(Name, SafeName),
      atom_concat('sec:', SafeName, Label)
    },
    latex(cmd(label(Label))).
section_label(_) -->
    [].

latex_section_level(chapter,       0).
latex_section_level(section,       1).
latex_section_level(subsection,    2).
latex_section_level(subsubsection, 3).
latex_section_level(paragraph,     4).

deepen_section_level(Level0, Level1) :-
    latex_section_level(Level0, N),
    N1 is N + 1,
    latex_section_level(Level1, N1).

%!  delete_unsafe_label_chars(+LabelIn, -LabelOut)
%
%   delete unsafe characters from LabelIn. Currently only deletes _,
%   as this appears  commonly  through   filenames,  but  cannot  be
%   handled through the LaTeX processing chain.

delete_unsafe_label_chars(LabelIn, LabelOut) :-
    atom_chars(LabelIn, Chars),
    delete(Chars, '_', CharsOut),
    atom_chars(LabelOut, CharsOut).


                 /*******************************
                 *         \ COMMANDS           *
                 *******************************/

%!  include(+File, +Type, +Options)// is det.
%
%   Called from [[File]].

include(PI, predicate, _) -->
    !,
    (   {   options(Options)
        ->  true
        ;   Options = []
        },
        latex_tokens_for_predicates(PI, Options)
    ->  []
    ;   latex(cmd(item(['[[', \predref(PI), ']]'])))
    ).
include(File, Type, Options) -->
    { existing_linked_file(File, Path) },
    !,
    include_file(Path, Type, Options).
include(File, _, _) -->
    latex(code(['[[', File, ']]'])).

include_file(Path, image, Options) -->
    { option(caption(Caption), Options) },
    !,
    latex(cmd(begin(figure, [no_escape(htbp)]))),
    latex(cmd(begin(center))),
    latex(cmd(includegraphics(Path))),
    latex(cmd(end(center))),
    latex(cmd(caption(Caption))),
    latex(cmd(end(figure))).
include_file(Path, image, _) -->
    !,
    latex(cmd(includegraphics(Path))).
include_file(Path, Type, _) -->
    { assertion(memberchk(Type, [prolog,wiki])),
      current_options(Options0),
      select_option(stand_alone(_), Options0, Options1, _),
      select_option(section_level(Level0), Options1, Options2, section),
      deepen_section_level(Level0, Level),
      Options = [stand_alone(false), section_level(Level)|Options2]
    },
    (   {Type == prolog}
    ->  latex_tokens_for_file(Path, Options)
    ;   latex_tokens_for_wiki_file(Path, Options)
    ).

%!  file(+File, +Options)// is det.
%
%   Called from implicitely linked files.  The HTML version creates
%   a hyperlink.  We just name the file.

file(File, _Options) -->
    { fragile },
    !,
    latex(cmd(texttt(File))).
file(File, _Options) -->
    latex(cmd(file(File))).

%!  predref(+PI)// is det.
%
%   Called  from  name/arity  or   name//arity    patterns   in  the
%   documentation.

predref(Module:Name/Arity) -->
    !,
    latex(cmd(qpredref(Module, Name, Arity))).
predref(Module:Name//Arity) -->
    latex(cmd(qdcgref(Module, Name, Arity))).
predref(Name/Arity) -->
    latex(cmd(predref(Name, Arity))).
predref(Name//Arity) -->
    latex(cmd(dcgref(Name, Arity))).

%!  nopredref(+PI)//
%
%   Called from ``name/arity``.

nopredref(Name/Arity) -->
    latex(cmd(nopredref(Name, Arity))).

%!  flagref(+Flag)//
%
%   Reference to a Prolog flag

flagref(Flag) -->
    latex(cmd(prologflag(Flag))).

%!  cite(+Citations) is det.
%
%   Emit a ``\cite{Citations}`` command

cite(Citations) -->
    { atomic_list_concat(Citations, ',', Atom) },
    latex(cmd(cite(Atom))).

%!  tags(+Tags:list(Tag)) is det.
%
%   Emit tag list produced by the   Wiki processor from the @keyword
%   commands.

tags([\args(Params)|Rest]) -->
    !,
    args(Params),
    tags_list(Rest).
tags(List) -->
    tags_list(List).

tags_list([]) -->
    [].
tags_list(List) -->
    [ nl(2) ],
    latex(cmd(begin(tags))),
    latex(List),
    latex(cmd(end(tags))),
    [ nl(2) ].

%!  tag(+Tag, +Values:list)// is det.
%
%   Called from \tag(Name, Values) terms produced by doc_wiki.pl.

tag(Tag, [One]) -->
    !,
    { doc_tag_title(Tag, Title) },
    latex([ cmd(tag(Title))
          | One
          ]).
tag(Tag, More) -->
    { doc_tag_title(Tag, Title) },
    latex([ cmd(mtag(Title)),
            \tag_value_list(More)
          ]).

tag_value_list([H|T]) -->
    latex(['- '|H]),
    (   { T \== [] }
    ->  [latex(' \\\\')],
        tag_value_list(T)
    ;   []
    ).

%!  args(+Params:list) is det.
%
%   Called from \args(List) created by   doc_wiki.pl.  Params is a
%   list of arg(Name, Descr).

args(Params) -->
    latex([ cmd(begin(arguments)),
            \arg_list(Params),
            cmd(end(arguments))
          ]).

arg_list([]) -->
    [].
arg_list([H|T]) -->
    argument(H),
    arg_list(T).

argument(arg(Name,Descr)) -->
    [ nl(1) ],
    latex(cmd(arg(Name))), [ latex(' & ') ],
    latex(Descr), [latex(' \\\\')].

%!  file_header(+File, +Options)// is det.
%
%   Create the file header.

file_header(File, Options) -->
    { memberchk(file(Title, Comment), Options),
      !,
      file_synopsis(File, Synopsis)
    },
    file_title([Synopsis, ': ', Title], File, Options),
    { is_structured_comment(Comment, Prefixes),
      string_codes(Comment, Codes),
      indented_lines(Codes, Prefixes, Lines),
      section_comment_header(Lines, _Header, Lines1),
      wiki_lines_to_dom(Lines1, [], DOM0),
      tags_to_front(DOM0, DOM)
    },
    latex(DOM),
    latex(cmd(vspace('0.7cm'))).
file_header(File, Options) -->
    { file_synopsis(File, Synopsis)
    },
    file_title([Synopsis], File, Options).

tags_to_front(DOM0, DOM) :-
    append(Content, [\tags(Tags)], DOM0),
    !,
    DOM = [\tags(Tags)|Content].
tags_to_front(DOM, DOM).

file_synopsis(File, Synopsis) :-
    file_name_on_path(File, Term),
    unquote_filespec(Term, Unquoted),
    format(atom(Synopsis), '~w', [Unquoted]).


%!  file_title(+Title:list, +File, +Options)// is det
%
%   Emit the file-header and manipulation buttons.

file_title(Title, File, Options) -->
    { option(section_level(Level), Options, section),
      Section =.. [Level,Title],
      file_base_name(File, BaseExt),
      file_name_extension(Base, _, BaseExt),
      delete_unsafe_label_chars(Base, SafeBase),
      atom_concat('sec:', SafeBase, Label)
    },
    latex(cmd(Section)),
    latex(cmd(label(Label))).


%!  objects(+Objects:list, +Options)// is det.
%
%   Emit the documentation body.

objects(Objects, Options) -->
    objects(Objects, [body], Options).

objects([], Mode, _) -->
    pop_mode(body, Mode, _).
objects([Obj|T], Mode, Options) -->
    object(Obj, Mode, Mode1, Options),
    objects(T, Mode1, Options).

object(doc(Obj,Pos,Comment), Mode0, Mode, Options) -->
    !,
    object(Obj, Pos, Comment, Mode0, Mode, Options).
object(Obj, Mode0, Mode, Options) -->
    { doc_comment(Obj, Pos, _Summary, Comment)
    },
    !,
    object(Obj, Pos, Comment, Mode0, Mode, Options).

object(Obj, Pos, Comment, Mode0, Mode, Options) -->
    { is_pi(Obj),
      !,
      is_structured_comment(Comment, Prefixes),
      string_codes(Comment, Codes),
      indented_lines(Codes, Prefixes, Lines),
      strip_module(user:Obj, Module, _),
      process_modes(Lines, Module, Pos, Modes, Args, Lines1),
      (   private(Obj, Options)
      ->  Class = privdef           % private definition
      ;   multifile(Obj, Options)
      ->  Class = multidef
      ;   Class = pubdef            % public definition
      ),
      (   Obj = Module:_
      ->  POptions = [module(Module)|Options]
      ;   POptions = Options
      ),
      DOM = [\pred_dt(Modes, Class, POptions), dd(class=defbody, DOM1)],
      wiki_lines_to_dom(Lines1, Args, DOM0),
      strip_leading_par(DOM0, DOM1),
      assert_documented(Obj)
    },
    need_mode(description, Mode0, Mode),
    latex(DOM).
object([Obj|Same], Pos, Comment, Mode0, Mode, Options) -->
    !,
    object(Obj, Pos, Comment, Mode0, Mode, Options),
    { maplist(assert_documented, Same) }.
object(Obj, _Pos, _Comment, Mode, Mode, _Options) -->
    { debug(pldoc, 'Skipped ~p', [Obj]) },
    [].

assert_documented(Obj) :-
    assert(documented(Obj)).


%!  need_mode(+Mode:atom, +Stack:list, -NewStack:list)// is det.
%
%   While predicates are part of a   description  list, sections are
%   not and we therefore  need  to   insert  <dl>...</dl>  into  the
%   output. We do so by demanding  an outer environment and push/pop
%   the required elements.

need_mode(Mode, Stack, Stack) -->
    { Stack = [Mode|_] },
    !,
    [].
need_mode(Mode, Stack, Rest) -->
    { memberchk(Mode, Stack)
    },
    !,
    pop_mode(Mode, Stack, Rest).
need_mode(Mode, Stack, [Mode|Stack]) -->
    !,
    latex(cmd(begin(Mode))).

pop_mode(Mode, Stack, Stack) -->
    { Stack = [Mode|_] },
    !,
    [].
pop_mode(Mode, [H|Rest0], Rest) -->
    latex(cmd(end(H))),
    pop_mode(Mode, Rest0, Rest).


%!  pred_dt(+Modes, +Class, Options)// is det.
%
%   Emit the \predicate{}{}{} header.
%
%   @param Modes    List as returned by process_modes/5.
%   @param Class    One of =privdef= or =pubdef=.
%
%   @tbd    Determinism

pred_dt(Modes, Class, Options) -->
    [nl(2)],
    pred_dt(Modes, [], _Done, [class(Class)|Options]).

pred_dt([], Done, Done, _) -->
    [].
pred_dt([H|T], Done0, Done, Options) -->
    pred_mode(H, Done0, Done1, Options),
    (   {T == []}
    ->  []
    ;   latex(cmd(nodescription)),
        pred_dt(T, Done1, Done, Options)
    ).

pred_mode(mode(Head,Vars), Done0, Done, Options) -->
    !,
    { bind_vars(Head, Vars) },
    pred_mode(Head, Done0, Done, Options).
pred_mode(Head is Det, Done0, Done, Options) -->
    !,
    anchored_pred_head(Head, Done0, Done, [det(Det)|Options]).
pred_mode(Head, Done0, Done, Options) -->
    anchored_pred_head(Head, Done0, Done, Options).

bind_vars(Term, Bindings) :-
    bind_vars(Bindings),
    anon_vars(Term).

bind_vars([]).
bind_vars([Name=Var|T]) :-
    Var = '$VAR'(Name),
    bind_vars(T).

%!  anon_vars(+Term) is det.
%
%   Bind remaining variables in Term to '$VAR'('_'), so they are
%   printed as '_'.

anon_vars(Var) :-
    var(Var),
    !,
    Var = '$VAR'('_').
anon_vars(Term) :-
    compound(Term),
    !,
    Term =.. [_|Args],
    maplist(anon_vars, Args).
anon_vars(_).


anchored_pred_head(Head, Done0, Done, Options) -->
    { pred_anchor_name(Head, PI, _Name) },
    (   { memberchk(PI, Done0) }
    ->  { Done = Done0 }
    ;   { Done = [PI|Done0] }
    ),
    pred_head(Head, Options).


%!  pred_head(+Term, Options) is det.
%
%   Emit a predicate head. The functor is  typeset as a =span= using
%   class =pred= and the arguments and =var= using class =arglist=.
%
%   @tbd Support determinism in operators

pred_head(//(Head), Options) -->
    !,
    { pred_attributes(Options, Atts),
      Head =.. [Functor|Args],
      length(Args, Arity)
    },
    latex(cmd(dcg(opt(Atts), Functor, Arity, \pred_args(Args, 1)))).
pred_head(Head, _Options) -->                   % Infix operators
    { Head =.. [Functor,Left,Right],
      Functor \== (:),
      is_op_type(Functor, infix), !
    },
    latex(cmd(infixop(Functor, \pred_arg(Left, 1), \pred_arg(Right, 2)))).
pred_head(Head, _Options) -->                   % Prefix operators
    { Head =.. [Functor,Arg],
      is_op_type(Functor, prefix), !
    },
    latex(cmd(prefixop(Functor, \pred_arg(Arg, 1)))).
pred_head(Head, _Options) -->                   % Postfix operators
    { Head =.. [Functor,Arg],
      is_op_type(Functor, postfix), !
    },
    latex(cmd(postfixop(Functor, \pred_arg(Arg, 1)))).
pred_head(M:Head, Options) -->                 % Qualified predicates
    !,
    { pred_attributes(Options, Atts),
      Head =.. [Functor|Args],
      length(Args, Arity)
    },
    latex(cmd(qpredicate(opt(Atts),
                         M,
                         Functor, Arity, \pred_args(Args, 1)))).
pred_head(Head, Options) -->                    % Plain terms
    { pred_attributes(Options, Atts),
      Head =.. [Functor|Args],
      length(Args, Arity)
    },
    latex(cmd(predicate(opt(Atts),
                        Functor, Arity, \pred_args(Args, 1)))).

%!  pred_attributes(+Options, -Attributes) is det.
%
%   Create a comma-separated list of   predicate attributes, such as
%   determinism, etc.

pred_attributes(Options, Attrs) :-
    findall(A, pred_att(Options, A), As),
    insert_comma(As, Attrs).

pred_att(Options, Det) :-
    option(det(Det), Options).
pred_att(Options, private) :-
    option(class(privdef), Options).
pred_att(Options, multifile) :-
    option(class(multidef), Options).

insert_comma([H1,H2|T0], [H1, ','|T]) :-
    !,
    insert_comma([H2|T0], T).
insert_comma(L, L).


:- if(current_predicate(is_dict/1)).
dict_kv_pairs([]) --> [].
dict_kv_pairs([H|T]) -->
    dict_kv(H),
    (   { T == [] }
    ->  []
    ;   latex(', '),
        dict_kv_pairs(T)
    ).

dict_kv(Key-Value) -->
    latex(cmd(key(Key))),
    latex(':'),
    term(Value).
:- endif.

pred_args([], _) -->
    [].
pred_args([H|T], I) -->
    pred_arg(H, I),
    (   {T==[]}
    ->  []
    ;   latex(', '),
        { I2 is I + 1 },
        pred_args(T, I2)
    ).

pred_arg(Var, I) -->
    { var(Var) },
    !,
    latex(['Arg', I]).
pred_arg(...(Term), I) -->
    !,
    pred_arg(Term, I),
    latex(cmd(ldots)).
pred_arg(Term, I) -->
    { Term =.. [Ind,Arg],
      mode_indicator(Ind)
    },
    !,
    latex([Ind, \pred_arg(Arg, I)]).
pred_arg(Arg:Type, _) -->
    !,
    latex([\argname(Arg), :, \argtype(Type)]).
pred_arg(Arg, _) -->
    { atom(Arg) },
    !,
    argname(Arg).
pred_arg(Arg, _) -->
    argtype(Arg).                   % arbitrary term

argname('$VAR'(Name)) -->
    !,
    latex(Name).
argname(Name) -->
    !,
    latex(Name).

argtype(Term) -->
    { format(string(S), '~W',
             [ Term,
               [ quoted(true),
                 numbervars(true)
               ]
             ]) },
    latex(S).

%!  term(+Text, +Term, +Bindings)// is det.
%
%   Process the \term element as produced by doc_wiki.pl.
%
%   @tbd    Properly merge with pred_head//1

term(_, Term, Bindings) -->
    { bind_vars(Bindings) },
    term(Term).

term('$VAR'(Name)) -->
    !,
    latex(cmd(arg(Name))).
term(Compound) -->
    { callable(Compound),
      !,
      Compound =.. [Functor|Args]
    },
    !,
    term_with_args(Functor, Args).
term(Rest) -->
    latex(Rest).

term_with_args(Functor, [Left, Right]) -->
    { is_op_type(Functor, infix) },
    !,
    latex(cmd(infixterm(Functor, \term(Left), \term(Right)))).
term_with_args(Functor, [Arg]) -->
    { is_op_type(Functor, prefix) },
    !,
    latex(cmd(prefixterm(Functor, \term(Arg)))).
term_with_args(Functor, [Arg]) -->
    { is_op_type(Functor, postfix) },
    !,
    latex(cmd(postfixterm(Functor, \term(Arg)))).
term_with_args(Functor, Args) -->
    latex(cmd(term(Functor, \pred_args(Args, 1)))).


%!  termitem(+Text, +Term, +Bindings)// is det.
%
%   Create a termitem or one of its variations.

termitem(_Text, Term, Bindings) -->
    { bind_vars(Bindings) },
    termitem(Term).

termitem('$VAR'(Name)) -->
    !,
    latex(cmd(termitem(var(Name), ''))).
:- if(current_predicate(is_dict/1)).
termitem(Dict) -->
    { is_dict(Dict),
      !,
      dict_pairs(Dict, Tag, Pairs)
    },
    latex(cmd(dictitem(Tag, \dict_kv_pairs(Pairs)))).
:- endif.
termitem(Compound) -->
    { callable(Compound),
      !,
      Compound =.. [Functor|Args]
    },
    !,
    termitem_with_args(Functor, Args).
termitem(Rest) -->
    latex(cmd(termitem(Rest, ''))).

termitem_with_args(Functor, [Left, Right]) -->
    { is_op_type(Functor, infix) },
    !,
    latex(cmd(infixtermitem(Functor, \term(Left), \term(Right)))).
termitem_with_args(Functor, [Arg]) -->
    { is_op_type(Functor, prefix) },
    !,
    latex(cmd(prefixtermitem(Functor, \term(Arg)))).
termitem_with_args(Functor, [Arg]) -->
    { is_op_type(Functor, postfix) },
    !,
    latex(cmd(postfixtermitem(Functor, \term(Arg)))).
termitem_with_args({}, [Arg]) -->
    !,
    latex(cmd(curltermitem(\argtype(Arg)))).
termitem_with_args(Functor, Args) -->
    latex(cmd(termitem(Functor, \pred_args(Args, 1)))).


%!  latex_table(+Attrs, +Content)// is det.
%
%   Emit a table in LaTeX.

latex_table(_Attrs, Content) -->
    { max_columns(Content, 0, _, -, Wittness),
      col_align(Wittness, 1, Content, Align),
      atomics_to_string(Align, '|', S0),
      atomic_list_concat(['|',S0,'|'], Format)
    },
%       latex(cmd(begin(table, opt(h)))),
    latex(cmd(begin(quote))),
    latex(cmd(begin(tabulary,
                    no_escape('0.9\\textwidth'),
                    no_escape(Format)))),
    latex(cmd(hline)),
    rows(Content),
    latex(cmd(hline)),
    latex(cmd(end(tabulary))),
    latex(cmd(end(quote))).
%       latex(cmd(end(table))).

max_columns([], C, C, W, W).
max_columns([tr(List)|T], C0, C, _, W) :-
    length(List, C1),
    C1 >= C0,		% take last as wittness to avoid getting the header
    !,
    max_columns(T, C1, C, List, W).
max_columns([_|T], C0, C, W0, W) :-
    max_columns(T, C0, C, W0, W).

col_align([], _, _, []).
col_align([CH|CT], Col, Rows, [AH|AT]) :-
    (   member(tr(Cells), Rows),
        nth1(Col, Cells, Cell),
        auto_par(Cell)
    ->  Wrap = auto
    ;   Wrap = false
    ),
    col_align(CH, Wrap, AH),
    Col1 is Col+1,
    col_align(CT, Col1, Rows, AT).

col_align(td(class=Class,_), Wrap, Align) :-
    align_class(Class, Wrap, Align),
    !.
col_align(_, auto, 'L') :- !.
col_align(_, false, 'l').

align_class(left,   auto, 'L').
align_class(center, auto, 'C').
align_class(right,  auto, 'R').
align_class(left,   false, 'l').
align_class(center, false, 'c').
align_class(right,  false, 'r').

rows([]) -->
    [].
rows([tr(Content)|T]) -->
    row(Content),
    rows(T).

row([]) -->
    [ latex(' \\\\'), nl(1) ].
row([td(_Attrs, Content)|T]) -->
    !,
    row([td(Content)|T]).
row([td(Content)|T]) -->
    latex(Content),
    (   {T == []}
    ->  []
    ;   [ latex(' & ') ]
    ),
    row(T).
row([th(Content)|T]) -->
    latex(cmd(textbf(Content))),
    (   {T == []}
    ->  []
    ;   [ latex(' & ') ]
    ),
    row(T).

%!  auto_par(+Content) is semidet.
%
%   True when cell Content is a good candidate for auto-wrapping.

auto_par(Content) :-
    phrase(html_text(Content), Words),
    length(Words, WC),
    WC > 1,
    atomics_to_string(Words, Text),
    string_length(Text, Width),
    Width > 15.

html_text([]) -->
    !.
html_text([H|T]) -->
    !,
    html_text(H),
    html_text(T).
html_text(\predref(Name/Arity)) -->
    !,
    { format(string(S), '~q/~q', [Name, Arity]) },
    [S].
html_text(Compound) -->
    { compound(Compound),
      !,
      functor(Compound, _Name, Arity),
      arg(Arity, Compound, Content)
    },
    html_text(Content).
html_text(Word) -->
    [Word].




                 /*******************************
                 *      SUMMARY PROCESSING      *
                 *******************************/

%!  latex_summary(+Options)
%
%   If Options contains  summary(+File),  write   a  summary  of all
%   documented predicates to File.

latex_summary(Options) :-
    option(summary(File), Options),
    !,
    findall(Obj, summary_obj(Obj), Objs),
    maplist(pi_sort_key, Objs, Keyed),
    keysort(Keyed, KSorted),
    pairs_values(KSorted, SortedObj),
    phrase(summarylist(SortedObj, Options), Tokens),
    open(File, write, Out),
    call_cleanup(print_latex(Out, Tokens, Options),
                 close(Out)).
latex_summary(_) :-
    retractall(documented(_)).

summary_obj(Obj) :-
    documented(Obj),
    pi_head(Obj, Head),
    \+ xref_hook(Head).

pi_head(M:PI, M:Head) :-
    !,
    pi_head(PI, Head).
pi_head(Name/Arity, Head) :-
    functor(Head, Name, Arity).
pi_head(Name//DCGArity, Head) :-
    Arity is DCGArity+2,
    functor(Head, Name, Arity).


pi_sort_key(M:PI, PI-(M:PI)) :- !.
pi_sort_key(PI, PI-PI).

object_name_arity(_:Term, Type, Name, Arity) :-
    nonvar(Term),
    !,
    object_name_arity(Term, Type, Name, Arity).
object_name_arity(Name/Arity, pred, Name, Arity).
object_name_arity(Name//Arity, dcg, Name, Arity).

summarylist(Objs, Options) -->
    latex(cmd(begin(summarylist, ll))),
    summary(Objs, Options),
    latex(cmd(end(summarylist))).

summary([], _) -->
    [].
summary([H|T], Options) -->
    summary_line(H, Options),
    summary(T, Options).

summary_line(Obj, _Options) -->
    { doc_comment(Obj, _Pos, Summary, _Comment),
      !,
      atom_codes(Summary, Codes),
      phrase(pldoc_wiki:line_tokens(Tokens), Codes), % TBD: proper export
      object_name_arity(Obj, Type, Name, Arity)
    },
    (   {Type == dcg}
    ->  latex(cmd(dcgsummary(Name, Arity, Tokens)))
    ;   { strip_module(Obj, M, _),
          current_op(Pri, Ass, M:Name)
        }
    ->  latex(cmd(oppredsummary(Name, Arity, Ass, Pri, Tokens)))
    ;   latex(cmd(predicatesummary(Name, Arity, Tokens)))
    ).
summary_line(Obj, _Options) -->
    { print_message(warning, pldoc(no_summary_for(Obj)))
    }.

                 /*******************************
                 *          PRINT TOKENS        *
                 *******************************/

print_latex(Out, Tokens, Options) :-
    latex_header(Out, Options),
    print_latex_tokens(Tokens, Out),
    latex_footer(Out, Options).


%!  print_latex_tokens(+Tokens, +Out)
%
%   Print primitive LaTeX tokens to Output

print_latex_tokens([], _).
print_latex_tokens([nl(N)|T0], Out) :-
    !,
    max_nl(T0, T, N, NL),
    nl(Out, NL),
    print_latex_tokens(T, Out).
print_latex_tokens([nl_exact(N)|T0], Out) :-
    !,
    nl_exact(T0, T,N, NL),
    nl(Out, NL),
    print_latex_tokens(T, Out).
print_latex_tokens([H|T], Out) :-
    print_latex_token(H, Out),
    print_latex_tokens(T, Out).

print_latex_token(cmd(Cmd), Out) :-
    !,
    format(Out, '\\~w', [Cmd]).
print_latex_token(curl(open), Out) :-
    !,
    format(Out, '{', []).
print_latex_token(curl(close), Out) :-
    !,
    format(Out, '}', []).
print_latex_token(indent(N), Out) :-
    !,
    format(Out, '~t~*|', [N]).
print_latex_token(nl(N), Out) :-
    !,
    format(Out, '~N', []),
    forall(between(2,N,_), nl(Out)).
print_latex_token(verb(Verb), Out) :-
    is_list(Verb), Verb \== [],
    !,
    atomic_list_concat(Verb, Atom),
    print_latex_token(verb(Atom), Out).
print_latex_token(verb(Verb), Out) :-
    !,
    (   member(C, [$,'|',@,=,'"',^,!]),
        \+ sub_atom(Verb, _, _, _, C)
    ->  atom_replace_char(Verb, '\n', ' ', Verb2),
        format(Out, '\\verb~w~w~w', [C,Verb2,C])
    ;   assertion(fail)
    ).
print_latex_token(code(Code), Out) :-
    !,
    format(Out, '~N\\begin{code}~n', []),
    format(Out, '~w', [Code]),
    format(Out, '~N\\end{code}', []).
print_latex_token(latex(Code), Out) :-
    !,
    write(Out, Code).
print_latex_token(w(Word), Out) :-
    !,
    print_latex(Out, Word).
print_latex_token(no_escape(Text), Out) :-
    !,
    write(Out, Text).
print_latex_token(url_escape(Text), Out) :-
    !,
    print_url(Out, Text).
print_latex_token(Rest, Out) :-
    (   atomic(Rest)
    ->  print_latex(Out, Rest)
    ;   %type_error(latex_token, Rest)
        write(Out, Rest)
    ).

atom_replace_char(In, From, To, Out) :-
    sub_atom(In, _, _, _, From),
    !,
    atom_chars(In, CharsIn),
    replace(CharsIn, From, To, CharsOut),
    atom_chars(Out, CharsOut).
atom_replace_char(In, _, _, In).

replace([], _, _, []).
replace([H|T0], H, N, [N|T]) :-
    !,
    replace(T0, H, N, T).
replace([H|T0], F, N, [H|T]) :-
    replace(T0, F, N, T).


%!  print_latex(+Out, +Text:atomic) is det.
%
%   Print Text, such that it comes out as normal LaTeX text.

print_latex(Out, String) :-
    atom_string(Atom, String),
    atom_chars(Atom, Chars),
    print_chars(Chars, Out).

print_chars([], _).
print_chars([H|T], Out) :-
    print_char(H, Out),
    print_chars(T, Out).


print_url(Out, String) :-
    string_chars(String, Chars),
    print_url_chars(Chars, Out).

print_url_chars([], _).
print_url_chars([H|T], Out) :-
    print_url_char(H, Out),
    print_url_chars(T, Out).

print_url_char('#', Out) :- !, write(Out, '\\#').
print_url_char(C,   Out) :- put_char(Out, C).


%!  max_nl(T0, T, M0, M)
%
%   Remove leading sequence of nl(N) and return the maximum of it.

max_nl([nl(M1)|T0], T, M0, M) :-
    !,
    M2 is max(M1, M0),
    max_nl(T0, T, M2, M).
max_nl([nl_exact(M1)|T0], T, _, M) :-
    !,
    nl_exact(T0, T, M1, M).
max_nl(T, T, M, M).

nl_exact([nl(_)|T0], T, M0, M) :-
    !,
    max_nl(T0, T, M0, M).
nl_exact([nl_exact(M1)|T0], T, M0, M) :-
    !,
    M2 is max(M1, M0),
    max_nl(T0, T, M2, M).
nl_exact(T, T, M, M).


nl(Out, N) :-
    forall(between(1, N, _), nl(Out)).


print_char('<', Out) :- !, write(Out, '$<$').
print_char('>', Out) :- !, write(Out, '$>$').
print_char('{', Out) :- !, write(Out, '\\{').
print_char('}', Out) :- !, write(Out, '\\}').
print_char('$', Out) :- !, write(Out, '\\$').
print_char('&', Out) :- !, write(Out, '\\&').
print_char('#', Out) :- !, write(Out, '\\#').
print_char('%', Out) :- !, write(Out, '\\%').
print_char('~', Out) :- !, write(Out, '\\Stilde{}').
print_char('\\',Out) :- !, write(Out, '\\bsl{}').
print_char('^', Out) :- !, write(Out, '\\Shat{}').
print_char('|', Out) :- !, write(Out, '\\Sbar{}').
print_char(C,   Out) :- put_char(Out, C).


%!  identifier(+Atom) is semidet.
%
%   True if Atom is (lower, alnum*).

identifier(Atom) :-
    atom_chars(Atom, [C0|Chars]),
    char_type(C0, lower),
    all_chartype(Chars, alnum).

all_chartype([], _).
all_chartype([H|T], Type) :-
    char_type(H, Type),
    all_chartype(T, Type).


                 /*******************************
                 *    LATEX SPECIAL SEQUENCES   *
                 *******************************/

%!  urldef_name(?String, ?DefName)
%
%   True if \DefName is  a  urldef   for  String.  UrlDefs are LaTeX
%   sequences that can be used to  represent strings with symbols in
%   fragile environments. Whenever a word can   be  expressed with a
%   urldef, we will  do  this  to   enhance  the  robustness  of the
%   generated LaTeX code.

:- dynamic
    urldef_name/2,
    urlchar/1,                      % true if C appears in ine of them
    urldefs_loaded/1.

%!  load_urldefs.
%!  load_urldefs(+File)
%
%   Load   =|\urldef|=   definitions   from    File   and   populate
%   urldef_name/2. See =|pldoc.sty|= for details.

load_urldefs :-
    urldefs_loaded(_),
    !.
load_urldefs :-
    absolute_file_name(library('pldoc/pldoc.sty'), File,
                       [ access(read) ]),
    load_urldefs(File).

load_urldefs(File) :-
    urldefs_loaded(File),
    !.
load_urldefs(File) :-
    open(File, read, In),
    call_cleanup((   read_line_to_codes(In, L0),
                     process_urldefs(L0, In)),
                 close(In)),
    assert(urldefs_loaded(File)).

process_urldefs(end_of_file, _) :- !.
process_urldefs(Line, In) :-
    (   phrase(urldef(Name, String), Line)
    ->  assert(urldef_name(String, Name)),
        assert_chars(String)
    ;   true
    ),
    read_line_to_codes(In, L2),
    process_urldefs(L2, In).

assert_chars(String) :-
    atom_chars(String, Chars),
    (   member(C, Chars),
        \+ urlchar(C),
        assert(urlchar(C)),
        fail
    ;   true
    ).

urldef(Name, String) -->
    "\\urldef{\\", string(NameS), "}\\satom{", string(StringS), "}",
    ws,
    (   "%"
    ->  string(_)
    ;   []
    ),
    eol,
    !,
    { atom_codes(Name, NameS),
      atom_codes(String, StringS)
    }.

ws --> [C], { C =< 32 }, !, ws.
ws --> [].

string([]) --> [].
string([H|T]) --> [H], string(T).

eol([],[]).


                 /*******************************
                 *         HEADER/FOOTER        *
                 *******************************/

latex_header(Out, Options) :-
    (   option(stand_alone(true), Options, true)
    ->  forall(header(Line), format(Out, '~w~n', [Line]))
    ;   true
    ),
    forall(generated(Line), format(Out, '~w~n', [Line])).

latex_footer(Out, Options) :-
    (   option(stand_alone(true), Options, true)
    ->  forall(footer(Line), format(Out, '~w~n', [Line]))
    ;   true
    ).

header('\\documentclass[11pt]{article}').
header('\\usepackage{times}').
header('\\usepackage{pldoc}').
header('\\sloppy').
header('\\makeindex').
header('').
header('\\begin{document}').

footer('').
footer('\\printindex').
footer('\\end{document}').

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


		 /*******************************
		 *            MESSAGES		*
		 *******************************/

:- multifile
    prolog:message//1.

prolog:message(pldoc(no_summary_for(Obj))) -->
    [ 'No summary documentation for ~p'-[Obj] ].