1/*  Part of SWI-Prolog
   2
   3    Author:        Jan Wielemaker
   4    E-mail:        J.Wielemaker@vu.nl
   5    WWW:           http://www.swi-prolog.org
   6    Copyright (c)  2006-2012, University of Amsterdam
   7                              VU University Amsterdam
   8    All rights reserved.
   9
  10    Redistribution and use in source and binary forms, with or without
  11    modification, are permitted provided that the following conditions
  12    are met:
  13
  14    1. Redistributions of source code must retain the above copyright
  15       notice, this list of conditions and the following disclaimer.
  16
  17    2. Redistributions in binary form must reproduce the above copyright
  18       notice, this list of conditions and the following disclaimer in
  19       the documentation and/or other materials provided with the
  20       distribution.
  21
  22    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  25    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  26    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  27    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  28    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  30    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  32    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33    POSSIBILITY OF SUCH DAMAGE.
  34*/
  35
  36:- module(pldoc_files,
  37          [ doc_save/2,                 % +File, +Options
  38            doc_pack/1                  % +Pack (re-export from doc_pack)
  39          ]).
  40:- use_module(library(pldoc), []).
  41:- use_module(pldoc(doc_html)).
  42:- use_module(pldoc(doc_index)).
  43:- use_module(pldoc(doc_pack)).
  44:- use_module(library(option)).
  45:- use_module(library(lists)).
  46:- use_module(library(filesex)).
  47
  48/** <module> Create stand-alone documentation files
  49
  50Create stand-alone documentation from a  bundle of source-files. Typical
  51use of the PlDoc package is to run   it as a web-server from the project
  52in progress, providing search and guaranteed consistency with the loaded
  53version. Creating stand-alone files as  provided   by  this  file can be
  54useful for printing or distribution.
  55
  56@tbd    Generate a predicate index?
  57*/
  58
  59:- predicate_options(doc_save/2, 2,
  60                     [ format(oneof([html])),
  61                       doc_root(atom),
  62                       man_server(atom),
  63                       index_file(atom),
  64                       if(oneof([loaded,true])),
  65                       recursive(boolean),
  66                       css(oneof([copy,inline])),
  67                       title(atom)
  68                     ]).
  69
  70
  71%!  doc_save(+FileOrDir, +Options)
  72%
  73%   Save documentation for FileOrDir to file(s).  Options include
  74%
  75%           * format(+Format)
  76%           Currently only supports =html=.
  77%
  78%           * doc_root(+Dir)
  79%           Save output to the given directory.  Default is to save
  80%           the documentation for a file in the same directory as
  81%           the file and for a directory in a subdirectory =doc=.
  82%
  83%           * title(+Title)
  84%           Title is an atom that provides the HTML title of the
  85%           main (index) page.  Only meaningful when generating
  86%           documentation for a directory.
  87%
  88%           * man_server(+RootURL)
  89%           Root of a manual server used for references to built-in
  90%           predicates. Default is
  91%           =|http://www.swi-prolog.org/pldoc/|=
  92%
  93%           * index_file(+Base)
  94%           Filename for directory indices.  Default is =index=.
  95%
  96%           * if(Condition)
  97%           What to do with files in a directory.  =loaded= (default)
  98%           only documents files loaded into the Prolog image.  =true=
  99%           documents all files.
 100%
 101%           * recursive(+Bool)
 102%           If =true=, recurse into subdirectories.
 103%
 104%           * css(+Mode)
 105%           If =copy=, copy the CSS file to created directories.
 106%           Using =inline=, include the CSS file into the created
 107%           files.  Currently, only the default =copy= is supported.
 108%
 109%   The typical use-case is to document the Prolog files that belong
 110%   to a project in the  current  directory.   To  do  this load the
 111%   Prolog  files  and  run  the   goal    below.   This  creates  a
 112%   sub-directory  =doc=  with  an  index  file  =|index.html|=.  It
 113%   replicates the directory structure  of   the  source  directory,
 114%   creating an HTML file for each Prolog file and an index file for
 115%   each sub-directory. A  copy  of  the   required  CSS  and  image
 116%   resources is copied to the =doc= directory.
 117%
 118%     ==
 119%     ?- doc_save(., [recursive(true)]).
 120%     ==
 121
 122doc_save(Spec, Options) :-
 123    doc_target(Spec, Target, Options),
 124    target_directory(Target, Dir),
 125    phrase(file_map(Target), FileMap),
 126    merge_options([ html_resources(pldoc_files),
 127                    source_link(false),
 128                    resource_directory(Dir)
 129                  ], Options, Options1),
 130    Options2 = [files(FileMap)|Options1],
 131    setup_call_cleanup(
 132        nb_setval(pldoc_options, Options2),
 133        generate(Target, Options2),
 134        nb_delete(pldoc_options)),
 135    copy_resources(Dir, Options2).
 136
 137
 138%!  generate(+Spec, +Options) is det.
 139%
 140%   Generate  documentation  for  the    specification   created  by
 141%   doc_target/2.
 142
 143generate([], _).
 144generate([H|T], Options) :-
 145    \+ \+ generate(H, Options),
 146    generate(T, Options).
 147generate(file(PlFile, DocFile), Options) :-
 148    b_setval(pldoc_output, DocFile),
 149    setup_call_cleanup(
 150        open(DocFile, write, Out, [encoding(utf8)]),
 151        with_output_to(Out, doc_for_file(PlFile, Options)),
 152        close(Out)).
 153generate(directory(Dir, IndexFile, Members, DirOptions), Options) :-
 154    append(DirOptions, Options, AllOptions),
 155    b_setval(pldoc_output, IndexFile),
 156    setup_call_cleanup(
 157        open(IndexFile, write, Out, [encoding(utf8)]),
 158        with_output_to(
 159            Out,
 160            doc_for_dir(Dir,
 161                        [ members(Members)
 162                        | AllOptions
 163                        ])),
 164        close(Out)),
 165    generate(Members, Options).
 166
 167
 168%!  doc_target(+Spec, -Target, +Options) is semidet.
 169%
 170%   Generate a structure describing what to document in what files.
 171%   This structure is a term:
 172%
 173%           * file(PlFile, DocFile)
 174%           Document PlFile in DocFile
 175%
 176%           * directory(Dir, IndexFile, Members, Options)
 177%           Document Dir in IndexFile.  Members is a list of
 178%           documentation structures.
 179
 180doc_target(FileOrDir, file(File, DocFile), Options) :-
 181    absolute_file_name(FileOrDir, File,
 182                       [ file_type(prolog),
 183                         file_errors(fail),
 184                         access(read)
 185                       ]),
 186    !,
 187    (   option(source_root(_), Options)
 188    ->  Options1 = Options
 189    ;   file_directory_name(File, FileDir),
 190        Options1 = [source_root(FileDir)|Options]
 191    ),
 192    document_file(File, DocFile, Options1).
 193doc_target(FileOrDir, directory(Dir, Index, Members, DirOptions), Options0) :-
 194    absolute_file_name(FileOrDir, Dir,
 195                       [ file_type(directory),
 196                         file_errors(fail),
 197                         access(read)
 198                       ]),
 199    !,
 200    (   option(source_root(_), Options0)            % recursive
 201    ->  Options = Options0
 202    ;   Options1 = [source_root(Dir)|Options0],     % top
 203        exclude(main_option, Options1, Options2),
 204        set_doc_root(Dir, Options2, Options)
 205    ),
 206    DirOptions = Options,
 207    document_file(Dir, Index, Options),
 208    findall(Member,
 209            (   prolog_file_in_dir(Dir, File, Options),
 210                doc_target(File, Member, Options)
 211            ),
 212            Members).
 213
 214%!  main_option(?Option)
 215%
 216%   Options that apply only to the main directory.
 217
 218main_option(title(_)).
 219main_option(readme(_)).
 220main_option(todo(_)).
 221
 222target_directory(directory(_, Index, _, _), Dir) :-
 223    file_directory_name(Index, Dir).
 224target_directory(file(_, DocFile), Dir) :-
 225    file_directory_name(DocFile, Dir).
 226
 227set_doc_root(_Dir, Options0, Options) :-
 228    option(doc_root(_), Options0),
 229    !,
 230    Options = Options0.
 231set_doc_root(Dir, Options0, Options) :-
 232    directory_file_path(Dir, doc, DocRoot),
 233    Options = [doc_root(DocRoot)|Options0].
 234
 235%!  file_map(+DocStruct, -List)
 236%
 237%   Create a list of file(PlFile, DocFile) for files that need to
 238%   be documented.
 239
 240file_map([]) -->
 241    [].
 242file_map([H|T]) -->
 243    file_map(H),
 244    file_map(T).
 245file_map(file(Src, Doc)) -->
 246    [ file(Src, Doc) ].
 247file_map(directory(_Dir, _Doc, Members, _Options)) -->
 248    file_map(Members).
 249
 250
 251
 252%!  document_file(+File, -DocFile, +Options) is semidet.
 253%
 254%   DocFile is the file into which to write the documentation for
 255%   File.  File must be a canonical Prolog source-file.
 256
 257document_file(File, DocFile, Options) :-
 258    (   option(if(loaded), Options, loaded)
 259    ->  (   source_file(File)
 260        ->  true
 261        ;   exists_directory(File),
 262            source_file(SrcFile),
 263            sub_atom(SrcFile, 0, _, _, File)
 264        ->  true
 265        )
 266    ;   true
 267    ),
 268    option(format(Format), Options, html),
 269    doc_extension(Format, Ext),
 270    (   exists_directory(File)
 271    ->  option(index_file(Index), Options, index),
 272        atomic_list_concat([File, /, Index, '.', Ext], DocFile0)
 273    ;   file_name_extension(Base, _, File),
 274        file_name_extension(Base, Ext, DocFile0)
 275    ),
 276    (   option(doc_root(Dir0), Options),
 277        ensure_slash(Dir0, Dir)
 278    ->  (   option(source_root(SrcTop), Options)
 279        ->  true
 280        ;   working_directory(SrcTop, SrcTop)
 281        ),
 282        directory_file_path(SrcTop, Local, DocFile0),
 283        directory_file_path(Dir, Local, DocFile),
 284        file_directory_name(DocFile, DocDir),
 285        ensure_dir(DocDir, Options)
 286    ;   DocFile = DocFile0
 287    ).
 288
 289
 290%!  doc_extension(+Format, -Extension) is det.
 291
 292doc_extension(html, html).
 293doc_extension(latex, tex).
 294
 295
 296%!  ensure_slash(+DirName, -WithSlash) is det.
 297%
 298%   Ensure WithSlash ends with a /.
 299
 300ensure_slash(DirName, WithSlash) :-
 301    (   sub_atom(DirName, _, _, 0, /)
 302    ->  WithSlash = DirName
 303    ;   atom_concat(DirName, /, WithSlash)
 304    ).
 305
 306
 307%!  ensure_dir(+Directory, +Options) is det.
 308%
 309%   Create Directory as mkdir -p.  May generate file errors.
 310
 311ensure_dir(Directory, _Options) :-
 312    exists_directory(Directory),
 313    !.
 314ensure_dir(Directory, Options) :-
 315    file_directory_name(Directory, Parent),
 316    Parent \== Directory,
 317    ensure_dir(Parent, Options),
 318    make_directory(Directory).
 319
 320
 321%!  prolog_file_in_dir(+Dir, -File, +Options) is nondet.
 322%
 323%   File is a file in Dir that must be documented.  Options:
 324%
 325%           * recursive(+Bool)
 326%           If =true=, also generate subdirectories
 327
 328prolog_file_in_dir(Dir, File, Options) :-
 329    (   option(if(loaded), Options, loaded)
 330    ->  source_file(File),
 331        file_directory_name(File, Dir)
 332    ;   user:prolog_file_type(Ext, prolog),
 333        \+ user:prolog_file_type(Ext, qlf),
 334        atomic_list_concat([Dir, '/*.', Ext], Pattern),
 335        expand_file_name(Pattern, Files),
 336        member(File, Files)
 337    ),
 338    file_base_name(File, Base),
 339    \+ blocked(Base).
 340prolog_file_in_dir(Dir, SubDir, Options) :-
 341    option(recursive(true), Options, false),
 342    option(doc_root(DocRoot), Options),
 343    atom_concat(Dir, '/*', Pattern),
 344    expand_file_name(Pattern, Matches),
 345    member(SubDir, Matches),
 346    SubDir \== DocRoot,
 347    exists_directory(SubDir).
 348
 349%!  blocked(+File) is semidet.
 350%
 351%   True if File is blocked from documentation.
 352
 353blocked('.plrc').
 354blocked('INDEX.pl').
 355
 356
 357                 /*******************************
 358                 *           RESOURCES          *
 359                 *******************************/
 360
 361%!  copy_resources(+Dir, +Options)
 362
 363copy_resources(Dir, Options) :-
 364    option(format(Format), Options, html),
 365    forall(doc_resource(Format, Res),
 366           ( absolute_file_name(pldoc(Res), File, [access(read)]),
 367             copy_file(File, Dir))).
 368
 369doc_resource(html, 'pldoc.css').
 370doc_resource(html, 'h1-bg.png').
 371doc_resource(html, 'h2-bg.png').
 372doc_resource(html, 'multi-bg.png').
 373doc_resource(html, 'priv-bg.png').
 374doc_resource(html, 'pub-bg.png').