From 74222843e5b08ca2953d385dd758e94155b1df20 Mon Sep 17 00:00:00 2001 From: Vitor Santos Costa Date: Tue, 8 May 2018 23:42:02 +0100 Subject: [PATCH] docs --- C/bignum.c | 13 +-- C/cmppreds.c | 2 +- C/eval.c | 2 +- C/exec.c | 2 +- C/flags.c | 6 +- CXX/yapi.cpp | 2 +- docs/custom/DoxygenLayout.xml | 114 -------------------- docs/md/#run.md# | 194 ---------------------------------- docs/md/INSTALL.md | 16 +-- docs/md/attributes.md | 5 +- docs/md/fli.md | 7 +- docs/md/library.md | 1 - docs/md/load_files.md | 4 +- docs/md/modules.md | 6 +- docs/md/run.md | 6 +- docs/md/syntax.md | 4 +- docs/md/yap.md | 2 +- library/apply.yap | 16 +-- library/charsio.yap | 4 +- library/rltree/yap_rl.c | 2 +- os/readterm.c | 4 +- pl/builtins.yap | 2 +- pl/udi.yap | 2 +- 23 files changed, 53 insertions(+), 363 deletions(-) delete mode 100644 docs/custom/DoxygenLayout.xml delete mode 100644 docs/md/#run.md# diff --git a/C/bignum.c b/C/bignum.c index 2b51b408a..ab9681a4e 100644 --- a/C/bignum.c +++ b/C/bignum.c @@ -451,7 +451,11 @@ static Int p_is_opaque(USES_REGS1) { return FALSE; } -static Int p_is_rational(USES_REGS1) { + /** @pred rational( ?:T ) + + Checks whether _T_ is a rational number. + */ + static Int p_is_rational(USES_REGS1) { Term t = Deref(ARG1); if (IsVarTerm(t)) return FALSE; @@ -510,13 +514,6 @@ void Yap_InitBigNums(void) { Yap_InitCPred("$bignum", 1, p_is_bignum, SafePredFlag); Yap_InitCPred("rational", 3, p_rational, 0); Yap_InitCPred("rational", 1, p_is_rational, SafePredFlag); - /** @pred rational( _T_) - - - Checks whether `T` is a rational number. - - - */ Yap_InitCPred("string", 1, p_is_string, SafePredFlag); Yap_InitCPred("opaque", 1, p_is_opaque, SafePredFlag); Yap_InitCPred("nb_set_bit", 2, p_nb_set_bit, SafePredFlag); diff --git a/C/cmppreds.c b/C/cmppreds.c index 7baa09762..0e066d7a3 100644 --- a/C/cmppreds.c +++ b/C/cmppreds.c @@ -723,7 +723,7 @@ static Int p_acomp(USES_REGS1) { /* $a_compare(?R,+X,+Y) */ } /** - @pred +_X_ =:= _Y_ is iso + @pred +X '=:=' Y is iso Equality of arithmetic expressions The value of the expression _X_ is equal to the value of expression _Y_. diff --git a/C/eval.c b/C/eval.c index cab3f1ce4..90ccf94d3 100644 --- a/C/eval.c +++ b/C/eval.c @@ -259,7 +259,7 @@ static Int p_isnan(USES_REGS1) { /* X isnan Y */ } /** - @pred isinf(? X:float) is det + @pred isinf(? X:float) is det Interface to the IEE754 `isinf` test. */ diff --git a/C/exec.c b/C/exec.c index 4b2ace0a7..3518f881c 100755 --- a/C/exec.c +++ b/C/exec.c @@ -54,7 +54,7 @@ static choiceptr cp_from_integer(Term cpt USES_REGS) { /** * Represents a choice-point as an offset to the top of local stack. This should * *be stable acroos gc or stack shifts. - * @method Yap_cp_as_integer + * @procedure Yap_cp_as_integer * @param cp pointer to choice-point * @return Term with offset */ diff --git a/C/flags.c b/C/flags.c index 1838c1e3a..3ae5969aa 100644 --- a/C/flags.c +++ b/C/flags.c @@ -1205,7 +1205,7 @@ static Int set_prolog_flag(USES_REGS1) { After executing this goal, YAP keeps information on the source of the predicates that will be consulted. This enables the use of -[listing/0](@ref listing), `listing/1` and [clause/2](@ref clause) for those +listing/0, listing/1 and clause/2 for those clauses. The same as `source_mode(_,on)` or as declaring all newly defined @@ -1713,9 +1713,9 @@ void Yap_InitFlags(bool bootstrap) { Yap_InitCPredBack("current_prolog_flag", 2, 1, current_prolog_flag, cont_yap_flag, 0); TR = tr0; - /** @pred prolog_flag(? _Flag_,- _Value__) + /** @pred prolog_flag( ?Flag, - Value) - Obtain the value for a YAP Prolog flag, same as current_prolog_flag/2_. + Obtain the value for a YAP Prolog flag, same as current_prolog_flag/2. */ Yap_InitCPredBack("prolog_flag", 3, 1, current_prolog_flag, cont_yap_flag, 0); diff --git a/CXX/yapi.cpp b/CXX/yapi.cpp index 86a1dfe6d..d6dcff868 100644 --- a/CXX/yapi.cpp +++ b/CXX/yapi.cpp @@ -69,7 +69,7 @@ restart: } } -YAPAtomTerm::YAPAtomTerm(char *s) { // build string +YAPAtomTerm::YAPAtomTerm(char s[]) { // build string BACKUP_H(); CACHE_REGS diff --git a/docs/custom/DoxygenLayout.xml b/docs/custom/DoxygenLayout.xml deleted file mode 100644 index d8c10604d..000000000 --- a/docs/custom/DoxygenLayout.xml +++ /dev/null @@ -1,114 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/md/#run.md# b/docs/md/#run.md# deleted file mode 100644 index 114d6c42a..000000000 --- a/docs/md/#run.md# +++ /dev/null @@ -1,194 +0,0 @@ - - -@page run Running YAP - -We next describe how to invoke YAP from the command-line, either interactively or as a script: - - * @subpage Running_YAP_Interactively - - * @subpage - -@page Running_YAP_Interactively Running YAP Interactively - -Most often you will want to use YAP in interactive mode. Assuming that -YAP is in the user's search path, the top-level can be invoked under -Unix with the following command: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -yap [-s n] [-h n] [-a n] [-c IP_HOST port ] [filename] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All the arguments and flags are optional and have the following meaning: - -+ -? -print a short error message. -+ -s _Size_ -allocate _Size_ KBytes for local and global stacks. The user may -specify M bytes. -+ -h _Size_ -allocate _Size_ KBytes for heap and auxiliary stacks -+ -t _Size_ -allocate _Size_ KBytes for the trail stack -+ -L _Size_ -SWI-compatible option to allocate _Size_ K bytes for local and global stacks, the local stack -cannot be expanded. To avoid confusion with the load option, _Size_ -must immediately follow the letter `L`. -+ -G _Size_ -SWI-compatible option to allocate _Size_ K bytes for local and global stacks; the global -stack cannot be expanded -+ -T _Size_ -SWI-compatible option to allocate _Size_ K bytes for the trail stack; the trail cannot be expanded. -+ -l _YAP_FILE_ -compile the Prolog file _YAP_FILE_ before entering the top-level. -+ -L _YAP_FILE_ -compile the Prolog file _YAP_FILE_ and then halt. This option is -useful for implementing scripts. -+ -g _Goal_ -run the goal _Goal_ before top-level. The goal is converted from -an atom to a Prolog term. -+ -z _Goal_ -run the goal _Goal_ as top-level. The goal is converted from -an atom to a Prolog term. -+ -b _BOOT_FILE_ -boot code is in Prolog file _BOOT_FILE_. The filename must define -the predicate `'$live'/0`. - 3333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333connect standard streams to host IP_HOST at port port -+ filename -restore state saved in the given file -+ -f -do not consult initial files -+ -q -do not print informational messages -+ -- -separator for arguments to Prolog code. These arguments are visible -through the unix/1 built-in predicate. - - -Note that YAP will output an error message on the following conditions: - -+ -a file name was given but the file does not exist or is not a saved -YAP state; - -+ -the necessary amount of memory could not be allocated; - -+ -the allocated memory is not enough to restore the state. - - - When restoring a saved state, YAP will allocate the -same amount of memory as that in use when the state was saved, unless a -different amount is specified by flags in the command line. By default, -YAP restores the file startup.yss from the current directory or from -the YAP library. - -+ -YAP usually boots from a saved state. The saved state will use the default -installation directory to search for the YAP binary unless you define -the environment variable YAPBINDIR. - -+ -YAP always tries to find saved states from the current directory - first. If it cannot it will use the environment variable YAPLIBDIR, if - defined, or search the default library directory. - - -YAP will try to find library files from the YAPSHAREDIR/library -directory. - -@subpage Running_Prolog_Files Running Prolog Files - -YAP can also be used to run Prolog files as scripts, at least in -Unix-like environments. A simple example is shown next (do not forget -that the shell comments are very important): - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/local/bin/yap -L -- -# -# Hello World script file using YAP -# -# put a dot because of syntax errors . - -vvvvvvvvvvvvvvvvvvvvvvvvvvv :- write('Hello World'), nl. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `#!` characters specify that the script should call the binary -file YAP. Notice that many systems will require the complete path to the -YAP binary. The `-L` flag indicates that YAP should consult the -current file when booting and then halt. The remaining arguments are -then passed to YAP. Note that YAP will skip the first lines if they -start with `#` (the comment sign for Unix's shell). YAP will -consult the file and execute any commands. - -A slightly more sophisticated example is: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/bin/yap -L -- -# -# Hello Wor ld script file using YAP -# . - -:- initialization(main). - -main :- write('Hello World'), nl. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `initialization` directive tells YAP to execute the goal main -after consulting the file. Source code is thus compiled and `main` -executed at the end. The `.` is useful while debugging the script -as a Prolog program: it guarantees that the syntax error will not -propagate to the Prolog code. - -Notice that the `--` is required so that the shell passes the extra -arguments to YAP. As an example, consider the following script -`dump_args`: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/bin/yap -L -- -#. - -main( [] ). -main( [H|T] ) :- - write( H ), nl, - main( T ). - -:- unix( argv(AllArgs) ), main( AllArgs ). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you this run this script with the arguments: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -./dump_args -s 10000 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -the script will start an YAP process with stack size `10MB`, and -the list of arguments to the process will be empty. - -Often one wants to run the script as any other program, and for this it -is convenient to ignore arguments to YAP. This is possible by using -`L --` as in the next version of `dump_args`: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/bin/yap -L -- - -main( [] ). -main( [H|T] ) :- - write( H ), nl, - main( T ). - -:- unix( argv(AllArgs) ), main( AllArgs ). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `--` indicates the next arguments are not for YAP. Instead, -they must be sent directly to the argv built-in. Hence, running - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -./dump_args test -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -will write `test` on the standard output. - diff --git a/docs/md/INSTALL.md b/docs/md/INSTALL.md index 5992e347a..971c2a974 100644 --- a/docs/md/INSTALL.md +++ b/docs/md/INSTALL.md @@ -5,7 +5,7 @@ This text includes instructions to download and install YAP. [TOC] -### Downloading YAP {#Download} +## Downloading YAP {#Download} The latest development version of Yap-6 is available source-only through GIT repositories. The main reference repository is at @@ -26,7 +26,7 @@ The first argument is the repository, the last argument is the (optional) target There are a variety of graphical interfaces to `git`, including GitHub's own [GitHub Desktop](https://desktop.github.com/) that supports Microsoft Windows and Apple OSX. A list with GUI applications, editor integration, and much more can be found at the [git Wiki](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools), -### Download Options +## Download Options It may be useful to know: @@ -41,7 +41,7 @@ It may be useful to know: version of doxygen adapted to Prolog that was used to generate these documents. -### Compiling YAP {#CompilingYAP} +## Compiling YAP {#CompilingYAP} YAP-6.3.4 is a [cmake](www.cmake.org) based system. We use `cmake` because it supports mosts popular software, can @@ -66,7 +66,7 @@ to install core YAP under `cmake`: YAP compiles cleanly under cross-compilers, and we have used the crosss-compilation system [mxe](http://mxe.cc/) system with good results. -### cmake +## cmake All Linux and BSD distributions include `cmake`, so does [Homebrew](https://brew.sh/) @@ -81,7 +81,7 @@ the [CMake site](https://www.cmake.org). If you have an older Linux you may need to compile from source, available at GitHub. -### Ensure that you have other necessary packages installed: +## Ensure that you have other necessary packages installed: + YAP requires [gmp]{https://gmplib.org/} for infinite precision integer and rational. Please ensure the development pacakage @@ -102,7 +102,7 @@ available at GitHub. + make sure to install Python-3, and not Python-2, -### Compile and Install +## Compile and Install 1: Create a directory, say `Build` and `cd` to the directory (`cd Build`). *YAP should not be compiled at its rootxo directory, some packages do not allow for that. @@ -177,7 +177,7 @@ You can also use `xcodebuild` from the command line. Bext follow instructions to fully compile YAP: -### Compilation Notes for OSX/Brew +## Compilation Notes for OSX/Brew Next follows a detailed description of a full install of YAP, including all the packages that YAP can use: @@ -210,7 +210,7 @@ brew install cudd cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl .. ~~~~~ -### Compilation Notes for Android +## Compilation Notes for Android Next we present the compilation process for Android. The environment is an OSX, but steps should be similar for Linux machines. We assume you have downloaded both the Android NDK and the Android SDK. diff --git a/docs/md/attributes.md b/docs/md/attributes.md index 056010d46..a92388d02 100644 --- a/docs/md/attributes.md +++ b/docs/md/attributes.md @@ -1,4 +1,5 @@ -### Attributed Variables and Co-Routining {#attributes} +Attributed Variables and Co-Routining {#AttributedVariables} +==================================== @ingroup extensions @@ -28,7 +29,7 @@ awi interface. [TOC] -#### SICStus Style attribute declarations. {#SICS_attributes} +## SICStus Style attribute declarations. {#SICS_attributes} The YAP library `atts` implements attribute variables in the style of SICStus Prolog. Attributed variables work as follows: diff --git a/docs/md/fli.md b/docs/md/fli.md index 1c5c57302..fbf01be9c 100644 --- a/docs/md/fli.md +++ b/docs/md/fli.md @@ -1,5 +1,5 @@ -### The Foreign Code Interface {#fli_c_cxx} - +The Foreign Code Interface {#fli_c_cxx} +================================ YAP provides the user with three facilities for writing predicates in a language other than Prolog. Under Unix systems, @@ -18,7 +18,7 @@ being designed to work with the swig (www.swig.orgv) interface compiler. @{ -#### YAP original C-interface {#ChYInterface} +## YAP original C-interface {#ChYInterface} Before describing in full detail how to interface to C code, we will examine a brief example. @@ -124,6 +124,7 @@ init_my_predicates() was passed as the third argument to load_foreign_files/3. The rest of this appendix describes exhaustively how to interface C to YAP. + ### Terms {#Manipulating_Terms} This section provides information about the primitives available to the C diff --git a/docs/md/library.md b/docs/md/library.md index de043a9fe..6fe1b9c32 100644 --- a/docs/md/library.md +++ b/docs/md/library.md @@ -32,7 +32,6 @@ YAP Prolog Library {#library} + @ref heaps + @ref lam_mpi + @ref line_utils -+ @ref swi_listing + @ref Log2MD + @ref mapargs + @ref maplist diff --git a/docs/md/load_files.md b/docs/md/load_files.md index 6f6766fef..52628a024 100644 --- a/docs/md/load_files.md +++ b/docs/md/load_files.md @@ -1,12 +1,12 @@ Loading and Organising YAP Programs {#load_files} ==================================== - @brief Next, we present the main predicates and directives available to load + Next, we present the main predicates and directives available to load files and to control the Prolog environment. + @ref YAPConsulting - + @ref YAPModules + - @page modules + @ref YAPBigLoad diff --git a/docs/md/modules.md b/docs/md/modules.md index e53bd8f67..7e648f07f 100644 --- a/docs/md/modules.md +++ b/docs/md/modules.md @@ -1,4 +1,4 @@ -The YAP Module system {#YAPModules} +The YAP Module system {#YAPModules} ======================= The YAP module system is based on the Quintus/SISCtus module @@ -40,7 +40,7 @@ the type-in module permanently by using the built-in `module/1`. [TOC] -#### Explicit Naming {#ExplicitNaming} +## Explicit Naming {#ExplicitNaming} The module system allows one to _explicitly_ specify the source mode for a clause by prefixing a clause with its module, say: @@ -228,7 +228,7 @@ X = 2 ? ; The state of the module system after this error is undefined. -### BuiltIn predicates {#ModuleBuiltins) +## BuiltIn predicates {#ModuleBuiltins) @\pred module(+ M:atom,+ L:list ) is directive the current file defines module _M_ with exports _L_. The list may include diff --git a/docs/md/run.md b/docs/md/run.md index 168154750..17f8e9acc 100644 --- a/docs/md/run.md +++ b/docs/md/run.md @@ -1,7 +1,7 @@ -## Running YAP {#run} - +Running YAP {#run} +============== We next describe how to invoke YAP in Unix systems. @@ -98,7 +98,7 @@ YAP always tries to find saved states from the current directory YAP will try to find library files from the YAPSHAREDIR/library directory. -### Running Prolog Files {#Running_Prolog_Files} +## Running Prolog Files {#Running_Prolog_Files} YAP can also be used to run Prolog files as scripts, at least in Unix-like environments. A simple example is shown next (do not forget diff --git a/docs/md/syntax.md b/docs/md/syntax.md index 2089b1a4b..ac0edd73d 100644 --- a/docs/md/syntax.md +++ b/docs/md/syntax.md @@ -353,7 +353,7 @@ other software components using the foreign language interface. In this section we only deal with I/O through streams, which includes file I/O as well as I/O through network sockets. -== @addgroup Stream_Encoding Wide character encodings on streams +== @addtogroup Stream_Encoding Wide character encodings on streams @ingroup WideChars The UCS standard describes all possible characters (or code points, as they include @@ -462,7 +462,7 @@ Prolog escape sequences while other streams generate an I/O exception. @{ -@addgroup BOM BOM: Byte Order Mark +@addtogroup BOM BOM: Byte Order Mark @ingroup WideChars From Stream Encoding, you may have got the impression that diff --git a/docs/md/yap.md b/docs/md/yap.md index 207038724..aef3ca5b8 100644 --- a/docs/md/yap.md +++ b/docs/md/yap.md @@ -17,7 +17,7 @@ Porto. The manual is organised as follows: -+ @subpage INSTALL.md ++ @subpage INSTALL + @subpage run diff --git a/library/apply.yap b/library/apply.yap index 72a63e4ea..ed55df91b 100644 --- a/library/apply.yap +++ b/library/apply.yap @@ -37,14 +37,14 @@ predicate to all elements of a list. The apply library is a _stub_, it just forwards definitions to the @ref maplist library. The predicates forwarded are: - - @ref maplist/2, - - @ref maplist/3, - - @ref maplist/4, - - @ref maplist/5, - - @ref include/3, - - @ref exclude/3, - - @ref partition/4, - - @ref partition/5 + - maplist/2, + - maplist/3, + - maplist/4, + - maplist/5, + - include/3, + - exclude/3, + - partition/4, + - partition/5 */ diff --git a/library/charsio.yap b/library/charsio.yap index 20788eea0..3adcf64fb 100644 --- a/library/charsio.yap +++ b/library/charsio.yap @@ -210,7 +210,7 @@ with_stream(Stream, Goal) :- current_output(Stream), call(Goal). -/** @pred read_from_chars(+ _Chars_, - _Term_) +/** @pred read_from_chars( + Chars, - Term) Parse the list of character codes _Chars_ and return the result in the term _Term_. The character codes to be read must terminate with @@ -218,7 +218,7 @@ a dot character such that either (i) the dot character is followed by blank characters; or (ii) the dot character is the last character in the string. -@compat The SWI-Prolog version does not require Codes to end +@note The SWI-Prolog version does not require Codes to end in a full-stop. */ read_from_chars("", end_of_file) :- !. diff --git a/library/rltree/yap_rl.c b/library/rltree/yap_rl.c index 52917b9b2..f1417e6f8 100644 --- a/library/rltree/yap_rl.c +++ b/library/rltree/yap_rl.c @@ -300,7 +300,7 @@ rl_freeze(void) { return (TRUE); } /** @pred rl_set_all( + Tree, Els). - * @addrogroup rl + * @addtogroup rl * */ diff --git a/os/readterm.c b/os/readterm.c index 628c83578..fd9646672 100644 --- a/os/readterm.c +++ b/os/readterm.c @@ -1425,7 +1425,7 @@ X_API Term Yap_BufferToTermWithPrioBindings(const char *s, Term opts, Term bind * @param _T_ the output term _T_, may be any term * @param _Options_ read_term/3 options. * - * @notes Originally from SWI-Prolog, in YAP only works with internalised + * @note Originally from SWI-Prolog, in YAP only works with internalised *atoms * Check read_term_from_atomic/3 for the general version. Also, the built-in *is @@ -1495,7 +1495,7 @@ static Int read_term_from_atomic(USES_REGS1) { * @param _T_ the output term _T_, may be any term * @param _Options_ read_term/3 options. * - * @notes Idea from SWI-Prolog, in YAP only works with strings + * Idea from SWI-Prolog, in YAP only works with strings * Check read_term_from_atomic/3 for the general version. */ static Int read_term_from_string(USES_REGS1) { diff --git a/pl/builtins.yap b/pl/builtins.yap index 3316e1d10..23d37f050 100644 --- a/pl/builtins.yap +++ b/pl/builtins.yap @@ -344,4 +344,4 @@ once(G) :- [] :- true. -%%% @} +%% @} diff --git a/pl/udi.yap b/pl/udi.yap index a8986f233..2b057fb8c 100644 --- a/pl/udi.yap +++ b/pl/udi.yap @@ -21,7 +21,7 @@ * * @brief User Defined Extensions * - * @addgroup UDI User Defined Extensions + * @addtogroup UDI User Defined Extensions * @ingroup extensions * *