Home

LPdoc Manual

1. 2 eee eese 127 A pee ees AR Ld Nr Em 132 EE 98 X xdvi 4 EE 132 RAVASAZE e ME 132 170 The Ipdoc Documentation Generator Property Index Property Index B bind E DEE 75 e DEE 87 clique 55 Ae EE ee ae 77 Gleef aii IN RED oe aed Se heed 78 COMPAL 2er bah isan IS RU 72 constraint lee id os 78 COVA iria A AN a aah 78 COVETEd EEN 78 D deprecated lin ws is e e dae TA 73 docstring 1 cde io qv Due lee m 25 56 E equiv 2 EE 75 error free 1 lid vi dee ees 75 evazi ET 75 exception AA aee EE A OEE 78 exceptions 2 2 p vie ees AR es Ph 78 F DE e tectum PS eC iym datis 79 eh EE 75 finite solutions 0 0 0 ccc eee eee 79 H have choicepoints l 0 eee ee eee 79 head p ttern 1 e Eed es whet eee peas 52 I SE Tc etter eh eho Bebe beta es SG 79 indep 2 ste ce ae ee 79 OS EL keen St ie AT epo oA d 72 instance 2 E ee rel A S 86 SE E GE REESEN 79 SR EE EE 73 L WINS AL Lat ne brute LRL as 80 longc ie tet A AO Leas 97 171 M il 2st eier E e EE Ed E heen PARTO 69 MOMO T uc over alveum ER e UAE 75 MShare Ae xx geht Sela pas A et e 80 mu t exclusive 1 ee Ie PY RR 80 N nabody 1 ive teer Ee Vs 54 E EE 74 native 2 E poh AES SS we ee 74 no choicepoints 1 veria pro xb 80 no exception l i esteem 81 no exception 2 wuss ve LR RARE dee AN 81 no rtcheck 1 5553 19 ve eh a ee oa ive 74 no signal EE 81 E E 81 non det i1 ce dE AS ES Sex 81 MONT OUNG diia ds eene hex mi 81
2. Example doc title Dr Strangelove doc subtitle How I Learned to Stop Worrying and Love the Bomb M The following properties should hold upon exit CommentType subtitle 2 SubtitleText is a documentation string docstring 1 Usage 3 doc CommentType SubtitleText Description Provides additional subtitle lines This can be e g an explanation of the application to add to the title the address of the author s of the application etc When generating documentation automatically the text in SubtitleText will be used accordingly Several of these declarations can appear per module which is useful for e g multiple line addresses Example doc subtitle_extra A Reference Manual doc subtitle extra Technical Report 1 1 0 The following properties should hold upon exit CommentType subtitle extra 2 SubtitleText is a documentation string docstring 1 Usage 4 doc CommentType SubtitleText Description The name of the logo image for the manual The following properties should hold upon exit CommentType logo 2 SubtitleText is any term term 1 Usage 5 doc CommentType AuthorText Description Provides the author s of the module or application If present when generating documentation for the module automatically the text in AuthorText will be placed in the corresponding chapter or front page There can be more than one of these declar
3. Description Documentation This assertion provides a text Comment for a given predicate Pred The following properties should hold at call time Pred is a head pattern head pattern 1 Comment is a text comment with admissible documentation commands The usual formatting commands that are applicable in comment strings are defined by stringcommand 1 See the 1pdoc manual for documentation on comments docstring 1 comment 2 DECLARATION Usage comment Pred Comment Description An alias for doc 2 deprecated for compatibility with older versions The following properties should hold at call time Pred is a head pattern head pattern 1 Comment is a text comment with admissible documentation commands The usual formatting commands that are applicable in comment strings are defined by stringcommand 1 See the 1pdoc manual for documentation on comments docstring 1 4 5 Documentation on exports assertions doc check 1 PREDICATE Usage check PropertyConjunction Description This assertion provides information on a clause program point position trust 1 in the body of a clause Calls to a check 1 assertion can appear in the body of a clause in any place where a literal can normally appear The property defined by PropertyConjunction should hold in all the run time stores corresponding to that program point See also Chapter 12 Run time checking of assertions page 103 The following properti
4. Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 29 2 Documentation on exports autodoc_bibrefs resolve bibliography 1 PREDICATE Usage resolve bibliography DocSt Description This predicate resolves bibliographical references The algorithm is as follows e Write all the bibliographical references to a aux file e Invoke BibTeX with a customized bet file that generates a pseudo docstring e Load the docstring and fix its syntax e Parse the docstring as a doctree e Extract Label Ref pairs from bibitem commands Both the docstring and label reference pairs are kept in the DocSt and used later to map symbolic references to textual labels The following properties should hold at call time docstate DocSt docstate 1 158 The Ipdoc Documentation Generator Chapter 30 Auxiliary Definitions 159 30 Auxiliary Definitions Author s Manuel Hermenegildo Jose F Morales 30 1 Usage and interface autodoc aux SI e Library usage use module library autodoc aux e Exports Predicates read_file 2 ascii_blank_lines 2 sh_exec 2 e Other modules used Application modules lpdocsrc src autodoc settings System library modules messages system make system extra lists nterna
5. Uncommenting this would make these not appear in the documentation doc hide bar 1 baz 1 This is a type definition in Prolog syntax declaration and code true regtype bar X var X is an acceptable kind of bar bar night bar day This is another type definition in Prolog syntax with no comment true regtype baz 1 baz a baz b Two type definitions in typedef syntax will be expanded to code as above 4 typedef aorb a b hh typedef listof or aorb X list X aorb Using functional notation regtype aorb 1 aorb a aorb b Should use the other function syntax which uses first argument for return regtype tree of 2 void tree call T tree of T tree of T tree of tree of T 44 tree oft void 44 tree off tree X L R Ah T X hh tree_of T L hh tree_of T R regtype list or aorb 2 list T aorb list_or_aorb T list_or_aorb _T This is a property definition This comment appears only in the place where the property itself is documented doc long 1 This is a property describing a list that is longish The definition is includedef long 1 Chapter 10 An Example Documenting a Library Module 91 hh hh y The comment here will be used to document any predicate which has an assertion which uses the property prop long L var L is rather long long L leng
6. The following properties hold globally struct T is side effect free struct T If the following properties hold at call time T is currently a term which is not a free variable then the following properties hold globally struct T is evaluable at compile time struct T The following properties hold upon exit T is a compound term Usage struct T Description T is a compound term The following properties hold globally This predicate is understood natively by CiaoPP gnd 1 The type of all terms without variables General properties gnd T The following properties hold globally gnd T is side effect free gnd T If the following properties hold at call time T is currently ground it contains no variables then the following properties hold globally gnd T is evaluable at compile time All calls of the form end CT are deterministic gnd T The following properties hold upon exit T is ground The following properties hold globally Indicates the type of test that a predicate performs analyisis Usage gnd T Description T is ground The following properties hold globally This predicate is understood natively by CiaoPP gndstr 1 General properties gndstr T The following properties hold globally gndstr T is side effect free 65 sideff 2 nonvar 1 eval 1 struct 1 native 1 REGTYPE sideff 2 ground 1
7. assrt body 1 REGTYPE This predicate defines the different types of syntax admissible in the bodies of pred 1 decl 1 etc assertions Such a body is of the form Pr DP CP gt AP GP 4 CO where fields between are optional e Pr is a head pattern head pattern 1 which describes the predicate or property and possibly gives some implicit call answer information e DP is a possibly empty complex argument property complex arg property 1 which expresses properties which are compatible with the predicate i e instantiations made by the predicate are compatible with the properties in the sense that applying the property at any point would not make it fail e CP is a possibly empty complex argument property complex arg property 1 which applies to the calls to the predicate 52 The Ipdoc Documentation Generator e AP is a possibly empty complex argument property complex arg property 1 which applies to the answers to the predicate if the predicate succeeds These only apply if the possibly empty properties given for calls in the assertion hold e GP is a possibly empty complex goal property complex goal property 1 which applies to the whole execution of a call to the predicate These only apply if the possibly empty properties given for calls in the assertion hold e CO is a comment string docstring 1 This comment only applies if the possibly empty properties given for calls in t
8. nonvar 1 ground 1 REGTYPE sideff 2 ground 1 ground 1 eval 1 nonvar 1 ground 1 REGTYPE sideff 2 nonvar 1 eval 1 Chapter 7 Basic data types and properties 71 character_code I The following properties hold upon exit I is an integer which is a character code character_code 1 Usage character_code T Description T is an integer which is a character code string 1 REGTYPE A string is a list of character codes The usual syntax for strings string is allowed which is equivalent to 0 s 0 t 0 r 0 i 0 n 0 g or 115 116 114 105 110 103 There is also a special Ciao syntax when the list is not complete st R is equivalent to 0 s 0 t R General properties string T The following properties hold globally string T is side effect free sideff 2 string T If the following properties hold at call time T is currently ground it contains no variables ground 1 then the following properties hold globally string T is evaluable at compile time eval 1 string T The following properties hold upon exit T is a string a list of character codes string 1 Usage string T Description T is a string a list of character codes num code 1 REGTYPE These are the ASCII codes which can appear in decimal representation of floating point and integer numbers including scientific notation and fractionary part predname 1
9. PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE 134 The Ipdoc Documentation Generator LPdoc Backends 135 LPdoc Backends 136 The Ipdoc Documentation Generator Chapter 20 Texinfo Backend 137 20 Texinfo Backend Author s Manuel Hermenegildo Jose F Morales 20 1 Usage and interface autodoc texinfo Va e Library usage use_module library autodoc_texinfo e Exports Predicates infodir_base 2 Multifiles autodoc_escape_string_hook 5 autodoc_rw_command_hook 4 autodoc_finish_ hook 1 autodoc_gen_alternative_hook 2 e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc filesystem lpdocsrc src autodoc structure lpdocsrc src autodoc index lpdocsrc src autodoc doctree lpdocsrc src autodoc images lpdocsrc src autodoc settings fastformat lpdocsrc src comments ciaodesrc makedir ConfigValues lpdocsrc src autodoc aux System library modules lists terms format messages system make make_rt file utils make system_ extra Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support y 20 2 Documentation on exports autodoc_texinfo infodir_base 2 PREDICATE No further documentation availab
10. Description This is a special case that is used to control which predicates are in cluded in the documentation Normally only exported predicates are documented A declaration doc doinclude PredName forces documentation for predicate or type property function PredName to be included even if PredName is not ex ported Also if PredName is reexported from another module a declaration doc doinclude PredName will force the documenation for PredName to appear directly in this module Example doc doinclude p 3 The following properties should hold upon exit CommentType doinclude 2 PredName is a Name Arity structure denoting a predicate name predname P A atm P nnegint A predname 1 Usage 20 doc CommentType PredName Description A different usage which allows the second argument of doc doinclude to bea list of predicate names The following properties should hold upon exit CommentType doinclude 2 PredName is a list of prednames list 2 Usage 21 doc CommentType PredName Description This is similar to the previous usage but has the opposite effect it signals that an exported predicate should not be included in the documentation Example doc hide p 3 The following properties should hold upon exit CommentType hide 2 PredName is a Name Arity structure denoting a predicate name predname P A atm P nnegint A
11. The following properties should hold upon exit CommentType filetype 2 FileType describes the intended use of a file filetype 1 Usage 24 doc CommentType FileName Description Do not document anything that comes from a file whose name after taking away the path and the suffix is FileName This is used for example when doc umenting packages to avoid the documenter from including documentation of certain other packages which the package being documented uses Example doc nodoc assertions The following properties should hold upon exit CommentType nodoc 2 FileName is an atom atm 1 version number 1 REGTYPE Version is a structure denoting a complete version number major version minor version and patch number version number Major Minor Patch int Major int Minor int Patch Usage version number Version Description Version is a complete version number Chapter 3 Documentation Mark up Language and Declarations 39 ymd_date 1 REGTYPE A Year Month Day structure denoting a date ymd_date Y M D int Y int M int D Usage ymd_date Date Description Date is a Year Month Day structure denoting a date time_struct 1 REGTYPE A struture containing time information time_struct Hours Minutes Seconds TimeZone int Hours int Minutes int Seconds atm TimeZone Usage time_struct Time Description Time contains time information
12. declarations can now be a list of predicate names A u File option is now supported so that a file including e g path alias definitions can be included this has the same functionality as the u option in ciaoc Now typing just gmake does nothing In order to do something at least one target should be specified This was necessary so that recursive invocations with empty arguments did nothing Chapter 1 Introduction 9 Added a new filetype part This allows splitting large documents into parts each of which groups a series of chapters e Other new functionality A style sheet can now be specified which allows modifying many charac teristics of the html output fonts colors background thanks to Per Cederberg Added limited support for changing page numbering in SETTINGS file The concept indexing commands index cindex and concept now work somewhat differently to make them consistent with other indexing com mands The old usage index is now called more appropriately global index Corre spondingly changed things so that now every definition goes to the global index in addition to its definitional index Imported files from module user are now documented separately Now a warning is issued if characters unsupported by info are used in section names Navigation in html docs was improved The table of contents in printed manuals now contains entries for the indi vidual descriptions of predicat
13. then the following properties hold globally sequence S T is evaluable at compile time sequence E T The following properties hold upon exit E is currently a term which is not a free variable T is currently ground it contains no variables Usage sequence S T Description S is a sequence of Ts sequence or list 2 Meta predicate with arguments sequence or list pred 1 General properties sequence or list S T The following properties hold globally sequence_or_list S T is side effect free sequence_or_list S T If the following properties hold at call time S is currently ground it contains no variables T is currently ground it contains no variables then the following properties hold globally sequence_or_list S T is evaluable at compile time sequence_or_list E T The following properties hold upon exit E is currently a term which is not a free variable T is currently ground it contains no variables Usage sequence_or_list S T Description S is a sequence or list of Ts character_code 1 General properties character_code T The following properties hold globally character_code T is side effect free character_code T If the following properties hold at call time T is currently a term which is not a free variable then the following properties hold globally character_code T is evaluable at compile time sideff 2 ground 1 ground 1 eval 1
14. use module library autodoc html resources e Exports Predicates prepare_web_skel 1 prepare mathjax 0 using mathjax 1 e Other modules used Application modules lpdocsrc src autodoc lpdocsrc src autodoc settings lpdocsrc src autodoc filesystem System library modules messages file utils make system extra distutils dirutils terms Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support GE 22 2 Documentation on exports autodoc html resources prepare web skel 1 PREDICATE No further documentation available for this predicate prepare mathjax 0 PREDICATE No further documentation available for this predicate using mathjax 1 PREDICATE No further documentation available for this predicate 142 The Ipdoc Documentation Generator Chapter 23 Template Support for the HTML Backend 143 23 Template Support for the HTML Backend Author s Jose F Morales 23 1 Usage and interface autodoc html template 3 e Library usage use module library autodoc html template e Exports Predicates img url 2 fmt html template 3 e Other modules used Application modules lpdocsrc src autodoc settings System library modules component registry component registry messages aggr
15. 10 An Example Documenting a Library Module ue erer aues Vaga dre ut is 89 11 Auto Documenter Output for the Example Modules atea alan 95 11 1 Usage and interface example mnodulel 95 11 2 Documentation on exports example module 95 o escrios r purre puede eire Y 95 IER EE 95 aorb 1 regtype EE 95 tree oE 2 regtype EE 96 listor aorb 2 regtype e dee ek rt E E 96 Q4 RE 96 ril pred geed 96 DA VDIB eege Ate ide Seo OH Radeon 97 EE EE 97 DESI AME PERLE 97 lone T prep tues osse Pedo Reste euo er 97 VERLA DEG ote se euro ahi d 98 mytype 1 pred iiie EORR ce dba 98 ENEE 98 SI REN 98 q l EC s vase alere exc ir PN RP OR 99 hist reetyDelrioco ter eq belief eo wl Ha pde e xd 99 11 3 Documentation on multifiles example module 100 E RE 100 11 4 Documentation on internals example module 101 list 2 retype e a ees ces wks eee be REA woe SR MR 101 og 2 modedgb X icut orte pii ue EE An ENS 101 Tova a UE E 102 12 Run time checking of assertions 103 12 1 Usage and interface rtchecks doc 104 13 Unit Testing Library 105 13 1 Additional NOLES uctus o recette oy Pers erate uk d ng d 105 13 2 Usage and interface unittest doc 106 vi The Ipdoc Documentation Generator 14 Installing lpd66 ssw eR RR E REA 107 14 1 Installing the source distribution Ipdoc 107 14 2 Other software packages requi
16. 153 lpdocsrc src autodoc texinfo 112 123 190 112 115 123 137 139 lpdocsrc src comments 145 lpdocsrc src component versions 147 lpdocsrc src distpkg download 139 M machine readable comments 25 32 nain DOY cu Er Pd exp E CR 34 nainfile IS a a 4 nain O cininieker td esegue x SS 3 4 Main ie Sm Loue ih eie teneo buius 3 4 main_absfile_for_subtarget 3 147 149 main_absfile_in_format 2 147 148 main output name 2 sese 147 149 make make rt 112 115 123 129 131 137 143 157 161 make system extra 112 115 123 131 137 141 143 147 157 159 161 Maket ile li niet degere ecce de 18 107 nakeinfoczc ll4ik Aeg RR XVIe V 108 makeinfo l 2 esis tales oes eim Led 131 133 h kertf 1 4 xod EE 131 133 MAN EE 19 20 Manuel Hermenegildo 15 25 41 51 57 61 77 89 107 111 115 123 137 145 155 157 159 Master index Ces ERE dedu TETUR 4 memnber 2 o Sdt de dE e 61 69 74 O EES EE 61 75 messages 112 115 137 141 143 159 161 meta predicate 1 c no RES 19 meta propsS ono A US 3 87 MODS uote s a op ote i bed tat toti 42 52 moded f i iode Ee tvi 42 47 52 nodtype 1 oare rre u a ERR 115 120 module COMO dr EE e H 34 module declaration sse es ess 111 CEET 111 nodule 2 ue noise ic iamdudum aed 111 nshare 1 c Lei deii RIBUS EE 77 80 mut exclusive 1
17. 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 prop assertion eL SEN a EN 45 46 EE 42 45 46 DEP Doi b A aep hr deer ts epe 42 46 87 PLOP abs DEET 88 properties ue Mi Pegs Shoe ee EF E 3 properties of computations 97 properties of execution etateg 97 properties basic icol e dE ee LESE 61 properties native sse eee 77 property new exon ex Sere pened ptite 45 191 property abettaction esses 88 property compatibility oo oo ooo 72 property_conjunction 1 48 49 51 53 property starterm 1 sess 51 53 propfunctor i sc Sh E RM Ad 51 56 providing information to the compiler 46 49 ps2pdfZi ii ae de EE halt AE 131 133 A EE 108 psview is ounce BAM eden 131 132 Q g l 7 Nus ERU AE HR did E TER TRUE 95 99 q 2s o Ludo teo IAS iaa dd ME A d 95 96 R B D EE 95 96 EEN 112 115 123 read file 2 bi slt os E 159 r6 ferencesolr xl c deefe ege wd 29 108 regtype assertiOn eene 60 regtype l asic lk eG ee 59 60 61 74 regtype 2 4 3 eek toes seen der 59 60 87 88 TOSTY PCS 2240 0 Sete bi ote EE 3 57 Teguliar type wins hose ches eae ee 60 regular type definitions 97 regular type expression 005 60 regular types a a aida 57 TOTS ia a 67 77 83 requested file formats 1 131 132 reset output dir db 0 esses
18. Forces local documentation even if hh not exported modedef og A gt gnd A This is a em mode definition the output is ground doc doinclude og 2 modedef og A T TCA gnd A This is a em parametric mode definition pred t A B C D og E list list int int list long B gt gnd O gnd A not fails This predicate uses Gem modes extensively tC A 95 A 2 Some other miscellaneous assertions Chapter 10 An Example Documenting a Library Module 93 Check is default assertion status anyway check pred u 0g check pred u int list mytype int uls d ud hh true status is normally compiler output true pred w list mytype mytype _ w _ doc doinclude is 2 trust pred is Num Expr arithexpression Expr num Num Typical way to describe document an external predicate e g written in C doc doinclude p 5 pred p og int in list int A steps_lb 1 length A pias eter SSS s ES d Version information The ciao el emacs mode allows automatic maintenance 94 The Ipdoc Documentation Generator Chapter 11 Auto Documenter Output for the Example Module 95 11 Auto Documenter Output for the Example Module Author s Anonymous Author 1 Anonymous Author 2 This is where general comments on the file go In this case the file is a library which contains some assertio
19. Quref URL introduces at point a reference to the Universal Resource Locator i e a WWW address URL uref tert URL introduces at point a reference to the Universal Resource Locator URL associated to the text tect email address introduces at point a reference to email address address emailt text address introduces at point a reference to the email address address associated to the text text author tezt tert will be printed in a normal font This command is used to ref erence the name of an author not necessarily establishing the module authorship Date and Version Qtoday prints the current date version prints the version of the current manual Mathematics The following commands are used to format text in mathematical math tert in line typeset the text formula 30 The Ipdoc Documentation Generator begin displaymath marks the beginning of a formula useful for long formulas end displaymath marks the end of the long formula defmathcmd cmd i n def defines the math command cmd taking n arguments which is expanded as def Arguments are denotated as 1 n inside def defmathcmd cmd def defines the math command cmd which is expanded as def with no ar guments Inclusion commands The following commands are used to include code or strings of text as part of doc umentation The latter may reside in external files or in the file being documented The f
20. The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is a comp assertion body g_assrt_body 1 prop 1 DECLARATION This assertion is similar to a pred 1 assertion but it flags that the predicate being docu mented is also a property Properties are standard predicates but which are guaranteed to terminate for any possible instantiation state of their argument s do not perform side effects which may interfere with the program behaviour and do not further instantiate their arguments or add new constraints Provided the above holds properties can thus be safely used as run time checks The program transformation used in ciaopp for run time checking guarantees the third re quirement It also performs some basic checks on properties which in most cases are enough for the second requirement However it is the user s responsibility to guaran tee termination of the properties defined See also Chapter 6 Declaring regular types page 57 for some considerations applicable to writing properties 46 prop 2 entry 1 exit 1 The Ipdoc Documentation Generator The set of properties is thus a strict subset of the set of predicates Note that properties can be used to describe characteristics of arguments in assertions and they can also be executed called as any other predicates Usage prop AssertionBody The following properti
21. W Lin Cost Analysis of Logic Programs ACM Transactions on Programming Languages and Systems 15 5 826 875 November 1993 S K Debray P L pez Garc a and M Hermenegildo Non Failure Analysis for Logic Programs In 1997 International Conference on Logic Programming pages 48 62 Cambridge MA June 1997 MIT Press Cambridge MA S K Debray P L pez Garc a M Hermenegildo and N W Lin Lower Bound Cost Estimation for Logic Programs In 1997 International Logic Programming Symposium pages 291 305 MIT Press Cambridge MA October 1997 M Hermenegildo A Documentation Generator for Logic Programming Systems Technical Report CLIP10 99 0 Facultad de Inform tica UPM September 1999 M Hermenegildo A Documentation Generator for C LP Systems In International Conference on Computational Logic CL2000 number 1861 in LNAI pages 1345 1361 Springer Verlag July 2000 D Jacobs and A Langen Compilation of Logic Programs for Restricted And Parallelism In European Symposium on Programming pages 284 297 1988 J Jaffar and M J Maher Constraint Logic Programming A Survey Journal of Logic Programming 19 20 503 581 1994 D Knuth Literate programming Computer Journal 27 97 111 1984 P L pez Garc a M Hermenegildo and S K Debray A Methodology for Granularity Based Control of Parallelism in Logic Programs Journal of Symbolic Computation Special Issue on Parallel Symbolic Computation
22. dechon ee eo me treo eter vido estet rdg 45 prop 2 decl iicet de rame Eher E VR era 46 entry Kee uo odds eh ats vitre eh et 46 Esa AT EE 46 E EE estela d uda I EA MES RENE SEAE 47 modedef 1 dec cis edm tee ren 4T EE AAA e ee Cooked melde SD aL 47 decida deel EE 47 EE 47 comment 2 NEE EE 48 4 5 Documentation on exports assertions doc 48 cheek pred ores ive RE ee ee uae PEOR De pete 48 trust pred ue no mee te SE d Ae 48 Zement pred shee ed aoe dag eRe oe Ae RENS EE 49 false Pred ege rec ERRAT re teas 49 5 Types and properties related to assertions 51 5 1 Usage and interface assertions props s s 5l 5 2 Documentation on exports assertions props 51 E E RE EE 51 head p ttern 1 prop 2 scene ee re Rt eto 02 complex arg property 1l regtype 52 property_conjunction 1 regtype 53 property starterm 1 regtype oooooooooooo 53 complex goal property 1 Dregtwpe 53 nabody t Prop 51 ee es ter AE a ae Sd s 54 dictionary regtype EE 54 c assrt body 1 regtype 3 e e 54 g assrt body 1 Testy pe scissa eei edet a ae 54 g assrt body 1 PER Pe coser teat tren RS eod 55 assrt stabus T regbype 22570412 oo ED rud 56 assrt_type 1 regtype mese reu E RPSL Eni 56 predfunctor 1 regtype sue o vao soa doen ato 56 propfunctor 1 reglype o 52x werd etd e ac xn 56 docstring 1 prop et ed ER E48 56 6 Declaring
23. imports etc now done solely by calls to c itf library and thus synchronized with ciaoc compiler Manuel Hermenegildo 10 The Ipdoc Documentation Generator Version 1 8 1999 3 24 21 15 33 MET This version completes the port to using the ciao 0 8 modular assertion processing library In addition it includes the following improvements Now if the name of a file being documented ends in doc the doc part is left out when referring to the file in the documentation useful if one would like to place the documentation declarations in different file It is now possible to declare via a comment 2 declaration the intended use of a file which is not a module i e a package user or include file which results in correct documentation of operator definitions new declarations etc The declaration is only needed for user files i e files to be loaded with ensure loaded 1 Separated generation of the manuals from their installation I e gmake install now does not force a gmake all which has to be done by hand This was necessary to ensure correct installation of distributed manuals even if modification dates are changed during installation Previously in some cases generation was triggered unnecessarily New v option allows using quieter by default operation when not debugging New option propmods makes the name of the module in which a property is defined appear in front of the property in the places where the prope
24. io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support y 18 2 Documentation on exports autodoc_structure docstr_node 4 PREDICATE No further documentation available for this predicate The predicate is of type data clean_docstr 0 PREDICATE No further documentation available for this predicate parse_structure 0 PREDICATE No further documentation available for this predicate standalone_docstr 1 PREDICATE No further documentation available for this predicate get_mainmod 1 PREDICATE No further documentation available for this predicate 130 The Ipdoc Documentation Generator get mainmod spec 1 PREDICATE No further documentation available for this predicate all component specs 1 PREDICATE No further documentation available for this predicate Chapter 19 Access to Default Settings 131 19 Access to Default Settings Author s Jose F Morales This module defines the setting values with some default values Note This part needs better documentation JFMC 19 1 Usage and interface autodoc_settings Va e Library usage use_module library autodoc_settings e Exports Predicates e Other modules used System library modules lpdoc_option 1 verify_settings 0 check setting 1 setting value or default 2 setting value or default 3 setting value 2 all setting values 2 get command option 1 requested
25. nent Edison Mera Added option f ConfigFile in lpdoc that uses the file ConfigFile instead the default LPSETTINGS pl Edison Mera Added option ascii that generates documentation in ascii plain format Edison Mera Added help option Is equal to h Edison Mera Added option testsettings to check that the settings file is correctly speci fied Edison Mera Changed generate html pointer 5 by generate html pointer 6 to let it work with any given directory and not only the working directory Edi son Mera The Ipdoc Documentation Generator Version 2 0 1999 8 17 17 28 52 CEST Major change to eliminate need for Makefiles Ipdoc is now a standalone com mand Manuel Hermenegildo Proceeds in parallel with further development of 1 9 Merge pending Previous changes incorporated since 1 8 e New functionality A new parameter PAPERTYPE can be set in the SETTINGS file which controls the format of printed output Manuel Hermenegildo Default pdf viewer is now ghostview sicne recent versions handle pdf well Manuel Hermenegildo Changed default style sheet in order to show lt PRE gt lines with a monospaced font Daniel Cabeza Gras Mode definitions now documented in a separate section The way they are documented has been improved Manuel Hermenegildo References in files now updated only if refs file is not empty Manuel Hermenegildo A copy of the html style sheet is now included in distributions Also Copies
26. sumlist 0 sumlist X R S sumlist R PS S is PS X to describe the type of calls for which the program has been designed i e those in which the first argument of sumlist 2 is indeed a list of integers The property instantiated to intlist 1 might be written as in the following Prolog definition prop instantiated to intlist 1 instantiated to intlist X nonvar X instantiated to intlist aux X instantiated to intlist aux instantiated to intlist aux X T integer X instantiated to intlist T Recall that the Prolog builtin integer 1 itself implements an instantiation check failing if called with a variable as the argument The property compatible with intlist 1 might in turn be written as follows also in Prolog prop compatible with intlist 1 compatible with intlist QO var X compatible with intlist X nonvar X compatible with intlist aux X compatible with intlist aux compatible with intlist aux X T int compat X compatible with intlist T int compat X var X int compat X nonvar X integer X Note that these predicates meet the criteria for being properties and thus the prop 1 decla ration is correct Ensuring that a property meets the criteria for not affecting the computation can sometimes make its coding somewhat tedious In some ways one would like to be able to write simply intlist intlist X R int X intlist R Incidentall
27. 112 resolve bibliograpbu 157 TECHECES iiie e EA vane um i inr ee are 103 rtchecks asrl0C6 ilo s elg ELI e 103 rtchecks callloC l 2 Nur du KN eg ees 104 rtchecks entry Ange SE e e EISE a e 103 rtchecks xlt 24 22 4299 V ID bL pe 103 rtchecks inline lees 103 rtchecks level lesse 103 rtchecks namefmt ooooooooooooo 104 rtchecks oredloc esee essen 103 rtchecks rt pl ue hb RR E tee ted 103 rtchecks tesSt ereer deu se da id o 103 rtchecks tr st i b sew Eu het b e 103 e owe ea eee anes ITE 131 133 run time checks 2 3 no d vals oie eee mE 45 running unit teste 105 192 S S 1 l1 pibe Pe oS 95 98 s assrt body l 44 45 46 47 51 54 SCEIDeO cte E e e RLCMIU AREE 26 S6Ctlonu ci ico Sq A aU USURIS C ie ENS 27 Section EE 123 125 section select prop 3 123 125 SECTIONS 0 3 uc he e pere eee YER 29 secttr diu pd ad 153 154 secttree_resolve B oooooo 153 154 Sequence 2 c teen vene 0p ed 61 69 sequence or Listr eee eee 61 70 setting value ececirigrt ialen iih 131 132 setting value or default 2 131 setting value or default 3 131 132 SETTINGS S ue ord A 5 8 9 29 SETTINGS pl 15 16 18 19 20 21 23 SETTINGS pl generated llus 15 shcexec 2 coss eiua edi IN x ES 159 sharing pieces of tert 30 sharing Set atico Lira herede dais
28. 123 a todoCc errorS iacu wWwELMI cues e ques 155 autodoc escape string hook 5 123 127 137 139 autodoc filesystem esee eses es 147 autodoc finish 1 sees 112 114 autodoc finish hook 1 112 114 137 138 139 145 autodoc gen alternative 2 112 114 autodoc gen alternative hook 2 112 114 137 138 140 145 autodoc gen dockree b 112 113 autodoc html ocio e a EE a A 111 139 autodoc html resources ees 141 autodoc html template sess 143 Global Index autodoc images sse nee 161 autodoc index ssl paw we VER e RE 151 utodoclman ili vA LER A Tv Eu 111 145 autodoc refsdb cc ccc cece eee ee 153 autodoc_rw_command_hook 4 123 127 137 139 145 autodoc Settings EEN ee eee eee e 131 autodoc state c cisci a dE 115 autodoc_structure essu onore nnne eno 129 autodoc texinfo eee eee 111 137 autodoc translate doctree 3 112 113 adtodocformats ere AN eL EP 3 automatic documentation 111 automatic documentation library 3 111 avoiding indentation 005 27 B backend alt formart sss 115 117 backend id 1l 113 115 116 138 139 145 148 backend ignores components 1 115 116 of W af x4 R n aE RSS repo 95 100 basename 1 o ns Vpe EA 113 147 149 ae i cbe LAN ERU esent it 18 basic props 3 25 42 51 61 77 87 95 10
29. 21 4 6 715 734 1996 K Muthukumar and M Hermenegildo Determination of Variable Dependence Information at Compile Time Through Ab stract Interpretation In 1989 North American Conference on Logic Programming pages 166 189 MIT Press October 1989 164 The Ipdoc Documentation Generator PBH97 G Puebla F Bueno and M Hermenegildo An Assertion Language for Debugging of Constraint Logic Programs Technical Report CLIP2 97 1 Facultad de Inform tica UPM July 1997 PBH98 G Puebla F Bueno and M Hermenegildo A Framework for Assertion based Debugging in Constraint Logic Programming In Proceedings of the JICSLP 98 Workshop on Types for CLP pages 3 15 Manch ester UK June 1998 PBHOO G Puebla F Bueno and M Hermenegildo An Assertion Language for Constraint Logic Programs In P Deransart M Hermenegildo and J Maluszynski editors Analysis and Visu alization Tools for Constraint Programming number 1870 in LNCS pages 23 61 Springer Verlag September 2000 Library Module Index Library Module Index A assertions 0B OQ VETERE DS EVE 41 assertions props ee nnne 51 BUT ODOC uu i e eee ee ro ER a STO TE n TA SUR UR 111 autodocs a x cel RI IX ind LPS Gau M E 159 autodoc bibrefs NEEN br eet pev 157 au todoc doctrina eee d bs 123 AULtOd C_erTOTS iii ai a 155 autodoc filesystem sese esse 147 autodoc html ss 26s a a 139 autodoc html resources eee nen 141 autodoc html
30. Arg3 is a list The following properties should hold globally Complies with the ISO Prolog standard All the calls of the form p Arg1 Arg2 Arg3 do not fail Usage 2 p Preds Value Assoc PREDICATE gnd 1 var 1 var 1 undefined property bar 1 baz 1 int 1 int 1 var 1 int 1 int 1 gnd 1 int 1 int 1 var 1 not fails 1 int 1 int 1 var 1 int 1 int 1 list 1 iso 1 not fails 1 Chapter 11 Auto Documenter Output for the Example Module Description This mode is also nice The following properties should hold at call time Preds is a free variable Value is a free variable Assoc is a list The following properties should hold upon exit Preds is an integer Value is an integer Assoc is a list The following properties should hold globally All the calls of the form p Preds Value Assoc do not fail Usage 3 Description Just playing around The following properties should hold upon exit Argl is a list Arg2 is an integer Arg3 is a list The following properties should hold globally All the calls of the form p Arg1 Arg2 Arg3 do not fail All the calls of the form p Arg1 Arg2 Arg3 do not fail 11 4 Documentation on internals example_module list 2 General properties list L T The following properties hold globally list L T is side effect free list L T If the following properties hold a
31. I idx get Lndices orun e e TA 151 152 image e DEE 30 images jLnserting eese 30 images Scaling z4 mice ELSE Sees i 30 lu g urlZ242 yx LLL ARA te CREME ERCRUM 143 include files iad ats hited HEN 22 38 include 1 bens Eee C EELER 22 38 including a predicate definition 30 including an Mage cece neriie 30 including code auc Messe eeu uua 30 including f1168 0 4 DRA E 30 including images ess 30 including or not authors 16 including or not bug Anfo 16 including or not changelog 16 including or not versions patches 16 indentation avoiding 0 27 indep d iid Su pattie tary eee Lae 77 78 79 80 indep 2 atados aid 77 78 79 80 index pages out of order 18 index comment 2 eee 16 112 Infon 5nd gib ier 1 4 19 20 21 24 27 107 info jpathliSt ee ai edu teer 20 infodir base 2 cene 137 Inner nata oko ae ee dh xS 103 insert show toc 3 esee 123 127 Global Index inserting images merei dre tere En 11 1n8t 2 ct Ph a RE t ues ed 61 72 installation eee Moe ZA See de scher GA 3 installation of manuals aa 18 INSTALLATION Updoe wie techs e ei ie 23 instance 2 EE 86 instantiation pGropertileg sss 97 int i Ju dedu 61 62 82 96 97 98 100 101 Interes 53 internalsS 22 25 2 6 B4 pitie e AE e 77 internals manual e cae cue tes es ta 3 22 introduction sit Lees ares eee ek Ea IG 3
32. Modified Makefile and SETTINGS to handle installation of manuals Manuel Hermenegildo Version 0 6 1998 2 10 Added new indices and options as well as more orthogonal handling of files Manuel Hermenegildo Version 0 4 1998 2 24 Added support for nroff m formatting e g for man pages Added support for optional selection of indices to be generated Added support for reexported predi cates Added low level ascii format Added option handling nobugs noauthors noversion nochangelog nopatches modes and headprops literalprops Fixed presentation when there are multiple kinds of assertions Better error checking for includefact includedef Manuel Hermenegildo Version 0 3 1998 2 10 Changed file reader to use Ciao native builtins As a result syntax files and full Ciao syntax now supported Major reorganization of the code to make formatting more orthogonal Now applications and libraries can be components or main files standalone or with components interchangeably includefact new predicate types used libraries now precisely detected docinclude option Manuel Hermenegildo Version 0 2 1997 12 16 Ported to native ciao Version handling selection of indices include Added gen eration of an html brief description for a global index Added unix manual page generation Added support for specifying library paths 1 option for htmlindex and man Installation improved now all files for one application in the same
33. REGTYPE General properties predname P The following properties hold globally predname P is side effect free sideff 2 predname P If the following properties hold at call time P is currently ground it contains no variables ground 1 then the following properties hold globally predname P is evaluable at compile time eval 1 predname P The following properties hold upon exit P is a Name Arity structure denoting a predicate name 72 The Ipdoc Documentation Generator predname P A atm P nnegint A predname 1 Usage predname P Description P is a Name Arity structure denoting a predicate name predname P A atm P nnegint A atm or atm list 1 REGTYPE General properties atm or atm list T The following properties hold globally atm_or_atm_list T is side effect free sideff 2 atm or atm list T If the following properties hold at call time T is currently ground it contains no variables ground 1 then the following properties hold globally atm or atm list T is evaluable at compile time eval 1 atm or atm list T The following properties hold upon exit T is an atom or a list of atoms atm or atm list 1 Usage atm or atm list T Description T is an atom or a list of atoms compat 2 PROPERTY This property captures the notion of type or property compatibility The instantiation or constraint state of the term is compatible with th
34. a string a list of character codes Name is a string a list of character codes Intermediate tree representation for documentation idx get indices 3 No further documentation available for this predicate is index cmd 1 No further documentation available for this predicate codetype 1 No further documentation available for this predicate normalize index cmd 3 No further documentation available for this predicate fmt idx env 7 No further documentation available for this predicate fmt index 3 No further documentation available for this predicate string 1 atom 1 atm 1 string 1 doctree 1 PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE Chapter 27 Database of Documentation References 153 27 Database of Documentation References Author s Jose F Morales This module stores and manages all the documentation references indices sections bibliog raphy etc It includes the generation of the table of contents 27 1 Usage and interface autodoc_refsdb SI e Library usage use module library autodoc refsdb e Exports Predicates compute_refs_and_biblio 1 prepare_current_refs 1 clean_current_refs 1 secttree_resolve 3 Regular Types secttree 1 e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc doctree lpdocsrc src autodoc structure lpdocsrc src autodoc_f
35. also allows compiling 1pdoc itself under C LP systems other than the Ciao system under which it is developed 2 7 Accessing on line manuals As mentioned previously it is possible to generate on line manuals automatically from the texic files essentially html info and man files This is done by simply including the corresponding options in the list of docformats in the SETTINGS p1 file and typing lpdoc all We now address the issue of how the different manuals can be read on line 2 7 1 Accessing html manuals Once generated the html files can be viewed using any standard WWW browser e g Firefox a command lpdoc htmlview is available which if there is an instance of a web browser running in the machine will make that instance visit the manual in html format To make these files publicly readable on the WWW they should be copied into a directory visible by browsers running in other machines such as home clip public html lpdoc docs usr home httpd htmldocs lpdoc docs etc As mentioned before this is easily done by set ting the docdir variable in the SETTINGS p1l file to this directory and typing lpdoc install 2 7 2 Accessing info manuals Generated info files are meant to be viewed by the Emacs editor or by the standalone info application both publicly available from the GNU project sites To view the a generated info file from Emacs manually i e before it is installed in a common area type C u M x info This will p
36. ate Ed sens 29 noindent commande 27 Qo command EE 31 Q0 command 3 SEH ht ea ILE Ken 31 Qoe command iz uxor sto RESI pla i nubi 31 ODE command i ic RUBRI TRIPS See dees 31 Bop command ade beie eI eH DEAE 28 0p Command 2e Ar 2458 UII IX UM E 27 pred commande 28 Gref command fics e g eens end a eel abe 29 Oresult Commande Se ed ENN en s 31 Osect Ton command eels a oes Rev be 27 Osp command iia a Saas ee 27 EE EE 31 subsection commande 27 Ob Commande ves ee eh aoe oe Pees be es 31 today commande 29 Ott commands i205 EE 27 u Command 3 4 ecu Soa IIIS 31 Ouref E eem is eet AUR 29 Oy command ated tied hos Ie EPA 31 Ovar Command ed te nem See dla ee dl ee 29 version commande 29 Hf Notes te E E e e 52 EE 52 AA paper c dn Re REFIERE OTT CCS 17 absfile f r aux 3 ij b uibus ix 147 149 absfile for subtarget 4 147 149 absfile to relfile 3 147 149 le EES et venue que iul ei ee aeri s 34 accents rou vg NU eio INI M 30 acceptable modes eee 52 acknowledgements nieres etere a ea lesse 34 EE 29 33 aggregates 112 115 129 131 143 147 151 153 157 all component specs 1 129 130 all indices 2 x boc REL 115 120 all setting values 2 131 132 analyzer output de a ert Pe LR 49 Anonymous Author 1 uote nre ee Is 95 The Ipdoc Documentation Generator Anonymous Author 2 sene 95 aorb 1 e eR WE EU LE UEM 95 A
37. be checked at run time eval 1 PROPERTY Meta predicate with arguments eval goal Usage eval Goal Description Goal is evaluable at compile time equiv 2 PROPERTY Meta predicate with arguments equiv goal goal Usage equiv Goali Goal2 Description Goal is equivalent to Goal2 bind ins 1 PROPERTY Meta predicate with arguments bind ins goal Usage bind_ins Goal Description Goal is binding insensitive error_free 1 PROPERTY Meta predicate with arguments error_free goal Usage error_free Goal Description Goal is error free memo 1 PROPERTY Meta predicate with arguments memo goal Usage memo Goal Description Goal should be memoized not unfolded filter 2 PROPERTY Usage filter Vars Goal Description Vars should be filtered during global control 76 The Ipdoc Documentation Generator flag values 1 REGTYPE Usage flag values X Description Define the valid flag values pe_type 1 PROPERTY Meta predicate with arguments pe_type goal Usage pe_type Goal Description Goal will be filtered in partial evaluation time according to the PE types defined in the assertion Chapter 8 Properties which are native to analyzers 77 8 Properties which are native to analyzers Author s Francisco Bueno Manuel Hermenegildo Pedro L pez Edison Mera This library contains a set of properties which are natively understood by the different pro gra
38. by the expression Y DL93 LGHD96 Meta predicate with arguments steps ub goal Usage steps ub X Y Description Y is a upper bound on the cost of any call of the form X tau 1 PROPERTY tau Types Types contains a list with the type associations for each variable in the form V T1 TN Note that tau is used in object oriented programs only Usage tau TypeInfo Description Types is a list of associations between variables and list of types The following properties hold globally This predicate is understood natively by CiaoPP native 1 86 The Ipdoc Documentation Generator terminates 1 PROPERTY terminates X Calls of the form X always terminate DLGH97 Meta predicate with arguments terminates goal Usage terminates X Description All calls of the form X terminate test type 2 PROPERTY Meta predicate with arguments test type goal Usage test type X T Description Indicates the type of test that a predicate performs Required by the nonfailure analyisis throws 2 PROPERTY Meta predicate with arguments throws goal Usage throws Goal Es Description Calls of the form Goal can throw only the exceptions that unify with the terms listed in Es user output 2 PROPERTY Meta predicate with arguments user output goal Usage user output Goal S Description Calls of the form Goal write S to standard output instance 2 PROPERTY Usage instance Te
39. calls Meta predicate with arguments possibly fails goal Usage possibly fails X Description Non failure is not ensured for calls of the form X Chapter 8 Properties which are native to analyzers 83 possibly nondet 1 PROPERTY possibly nondet X Non determinism is not ensured for all calls of the form X In other words nothing can be ensured about determinacy nor termination of such calls Usage possibly nondet X Description Non determinism is not ensured for calls of the form X relations 2 PROPERTY relations X N The goal X produces N solutions In other words N is the cardinality of the solution set of X Meta predicate with arguments relations goal Usage relations X N Description Goal X produces N solutions sideff hard 1 PROPERTY Meta predicate with arguments sideff hard goal Usage sideff hard X Description X has hard side effects i e those that might affect program execution e g assert retract sideff pure 1 PROPERTY Meta predicate with arguments sideff pure goal Usage sideff pure X Description X is pure i e has no side effects sideff soft 1 PROPERTY Meta predicate with arguments sideff soft goal Usage sideff soft X Description X has soft side effects i e those not affecting program execution e g input output signal 1 PROPERTY Meta predicate with arguments signal goal Usage signal Goal Description
40. dir prepared 2 PREDICATE Usage ensure_output_dir_prepared Backend Opts Description Ensure that the output directories for backend Backend are prepared get_autodoc_opts 3 PREDICATE Usage get autodoc opts Backend Mod Opts Description Get the list of documentation options Opts for the FileBase file The following properties should hold at call time Backend is an atom atm 1 Mod is an atom atm 1 Opts is a list of supported options list 2 autodoc gen doctree 5 PREDICATE Usage autodoc gen doctree Backend FileBase SourceSuffix pts Mod Description FileBase is the module specifier of the source file being documented without extension SourceSuffix is the suffix of the source The output is a file whose contents document the main file based on any assertions present in that file The documentation is produced in the format given by Backend the name of the output file also depends on Backend The formats supported are given by backend id 1 Call and exit should be compatible with Backend is a supported backend backend_id 1 FileBase is the base name of a file without extension basename 1 SourceSuffix is an atom atm 1 Opts is a list of supported_options list 2 Mod is an atom atm 1 fmt infodir entry 3 PREDICATE Usage fmt infodir entry DocSt Version Mod Description Generates a one line description ASCII of the application or library in a file for the
41. directory Manuel Hermenegildo Version 0 1 1997 7 30 First official version major rewrite from several previous prototypes autodocu mented Manuel Hermenegildo Version 0 0 1996 10 10 First prototype PART I LPdoc Reference Manual PART I LPdoc Reference Manual 13 14 The Ipdoc Documentation Generator Chapter 2 Generating Installing and Accessing Manuals 15 2 Generating Installing and Accessing Manuals Author s Manuel Hermenegildo l SES significant parts of this are obsolete They must be updated to describe Ipdoc version This section describes how to generate a manual semi automatically from a set of source files using 1pdoc how to install it in a public area and how to access it on line It also includes some recommendations for improving the layout of manuals usage tips and troubleshooting advice 2 1 Generating a manual from the Ciao Emacs mode If you use the Emacs editor highly recommended in all circumstances then the simplest way to quickly generate a manual is by doing it from the Ciao Emacs mode this mode comes with the Ciao Prolog distribution and is automatically installed with Ciao The Ciao Emacs mode provides menu and keyboard binding driven facilities for generating a stand alone document with the documentation corresponding to the file in the buffer being visited by Emacs This is specially useful while modifying the source of a file in order to check the output
42. eer Ru 22 38 user o tp t 2 oi dee de Sake ER 77 86 using citations cc cece cece eens 16 using_mathjax 1 00008 141 V a UV 53 96 977 98 100 101 variable Dames moi eR APR IB D s 41 Verbatim text hee WR dit ede os 27 verify settings eese sss 131 Versione EE 29 version maintenance mode for packages 37 versi n Ta TEE 36 version date 2 esee 123 127 version descriptor 1 25 32 36 version maintenance type 1l 36 37 39 version number 1 eene 38 version numstr 2 eee 123 127 version patch 2 v RE be ode 123 127 version String sess 123 127 EE 131 132 W WI deen d Abee ab E 95 98 word help Jaate ana epe eV dE 20 word help setup e l cece cece eee eee 20 word hel piel nie rpi iae tee lo A dates 20 ELE egen Un E ached ea CER 115 123 NNN ics tai he d ck hs 1 19 WWW address mel ee eee heey te 29 X EIN e berger erue qus du 17 A E EE E E E 131 132 xdvisize 1 v v dte IRAE 131 132 Y KEE PW ne vum 103 104 YE AA ANE EE 38 194 The Ipdoc Documentation Generator
43. execute the command 1pdoc d getinfo author summary getinfo The filesmyfile_author txt and myfile summary txt will be created If also the option d getinfo format html is used the files will have html extension and content Chapter 1 Introduction 5 1 3 lpdoc usage The following provides the different command line options available when invoking lpdoc This description is intended only for advanced users which might like to use 1pdoc in custom applications Note that the normal way to use 1pdoc is by setting parameters in an SETTINGS file see Section 2 2 Generating a manual page 15 TODO command line options not available here need cooperation with lpmake 1 4 Version Change Log Version 3 0 2011 7 7 16 33 15 CEST e Major redesign of the documentation generator LPdoc redesigned to work internally with a doctree representation a la Pillow Jose Morales A native HTML backend not generated from texi Jose Morales Allow custom website generation from LPdoc documents Jose Morales Two passes for document generation allowing resolution of bibliographical references in all backends including HTML Jose Morales doc structure 1 in SETTINGS allows structure in LPdoc documents sec tions can really be nested inside parts Jose Morales doc _ _ is the recommended syntax for documentation comments now Replacing comment by doc in LPdoc code updated documentation Jose Morales e G
44. exported predicates Ge If you need to write tests for predicates that are spread over several modules but work together then it is best to create a separate module and reexport to the predicates required to build the test This allows performing integration testing using the same syntax of the unit tests 4 The Ciao system includes a good and growing number of unit tests To run all the tests among the other standard tests within the CiaoDE run the following at the top level of the source tree ciaosetup runtests 106 The Ipdoc Documentation Generator 13 2 Usage and interface unittest doc N e Library usage use module library unittest e Other modules used Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support Chapter 14 Installing lpdoc 107 14 Installing Ipdoc Author s Manuel Hermenegildo This documentation is outdated The source distribution contains all the source code and libraries and can be compiled on a supported Prolog system lpdoc is developed using Ciao Prolog The latest publically distributed version of lpdoc is available from http www clip dia fi upm es Software Ciao A newer version in Beta test is often available in http www clip dia fi upm es Software Beta Cia
45. file As mentioned before lpdoc typically generates texinfo files From the texinfo files lpdoc can generate printed and on line manuals in several formats dvi ps ascii html info etc automatically using different publicly available packages Documentation in some other formats e g manl pages can be generated directly by 1pdoc selecting the appropriate options see below lpdoc can also generate directly includes generating parts of a master index of documents which can be placed in an installation directory and which will provide pointers to the individual manuals generated Using this feature lpdoc can maintain global html and or info documentation sites automatically see Section 2 5 Installing a generated manual in a public area page 18 Additionally 1pdoc can provide some data from the main prolog documentation file For this purpose the option getinfo can be used instead of specifying the format This option reads the asked fields from getinfo variable defined in SETTINGS pl or via arguments with d option lpdoc will generate files with main documentation file name as base name followed by one underscore the asked field got from getinfo and the extension The content of each of these files so also the extension is specified by getinfo format that can take the values html ascii texic For example to ask for the summary and the author fields from a prolog file called file pl with 1pdoc documentation we can
46. goal that should succeed after predicate n has been called The idea appears to be simple but note that due to the non determinism of logic programs the test engine needs to test all the solutions that can be tested up to given limits for example a maximum number of solutions or a given time out Properties specifies some global properties that the predicate should meet for example not fails means that the program does not fail exception error a b means that the program should throw the exception error a b and so on But there are some specific properties that only applies to testing specified in the module unittest_props pl for example times N specifies that the given test should be executed N times try sols N specifies that the first N solutions of the predicate predicate n are tested Comment is a string that document the test A convenient way to run these tests is by selecting options in the CiaoDbg menu within the development environment 1 Run tests in current module execute only the tests specified in the current module 2 Run tests in all related modules execute the tests specified in the module and in all the modules being used by this 3 Show untested predicates show the exported predicates that do not have any test asser tion 13 1 Additional notes 1 The test assertions allow performing unit testing i e in Ciao performing tests at the predicate level b The tests currently can only be applied to
47. hold at call time Argl is a free variable var 1 Arg2 is ground gnd 1 Arg2 is an integer int 1 The following properties should hold upon exit Argi is ground gnd 1 Argl is an integer int 1 Arg2 is an integer int 1 Usage 2 Description Non moded types are best used this way Call and exit should be compatible with Argl is an integer int 1 Arg2 is a list 1158 11 r 1 PREDICATE The predicate is of type data Usage r A Description This uses parametric types Chapter 11 Auto Documenter Output for the Example Module 97 The following properties should hold at call time A is a list list 1 The following properties should hold upon exit A is a list of ints list 2 A is ground gnd 1 The following properties should hold globally All the calls of the form r A do not fail not fails 1 p 1 PREDICATE Usage The following properties should hold at call time Argi is a free variable var 1 The following properties should hold upon exit Argl is a list list 1 p 5 PREDICATE Usage p Arg1 Arg2 Arg3 Arg4 A Call and exit should be compatible with Arel is an integer int 1 Arg3 is a list of ints list 2 The following properties should hold at call time Arg2 is currently ground it contains no variables ground 1 Arg4 is a free variable var 1 A is currently a term which is not a free variable nonvar 1 The follow
48. ii o See ees 15 generating from Emace sse ssssss 15 generating manuals s sss elles 15 German Puebla 46x aid Lu t ud A1 get autodoc opte 112 113 get cache dir 2 ege eee RR AS AES Ede 147 148 get command option 1 131 132 get doc 4 4 vut vod EI e Re 115 120 peti doc fietd 3 o erg ee 115 120 get doc field dict 3 115 120 get first loc for pred 3 115 121 getiidxbase Vivi RESRMN 151 Eget idxsub 23i veste eae RS 151 Eget mainmod 1 J c oric ara pede 129 Set mainmod specil oo 129 130 getzmod doc 3 cob ob EVE EIS 115 120 get output EEN 147 148 Eget subbase S icc net eae hehe hes 147 149 a A EE EE E E T 8 BA Ee bus 107 a eter 61 65 96 97 98 99 100 102 ndsti Pen eorr ie Par ait et 61 65 66 The Ipdoc Documentation Generator GNU general public license 1 GNU Make rts hs epe E Ee A 107 ground 1 65 66 68 69 70 71 72 73 77 78 80 97 99 101 BUNZEP EE 107 H hard side ffects cer unes 83 have choicepoints l 77 79 Neadspatvern oe sre hie ses vee He een 51 52 55 head_pattern 1 04 48 51 52 55 hiord rt 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 EM o nea ipea peret LEE ee vs 4 HTML lt lt obit rada EEN 1 html index pages ee ee deel ieee et eee 18 htulview d eg EN EE 131 133
49. index N e Library usage use_module library autodoc_index e Exports Predicates get_idxsub 2 get_idxbase 3 typeindex 5 idx_get_indices 3 is_index_cmd 1 codetype 1 normalize_index_cmd 3 fmt_idx_env 7 fmt_index 3 e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc filesystem lpdocsrc src autodoc doctree lpdocsrc src autodoc structure lpdocsrc src autodoc refsdb System library modules dict lists aggregates Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 26 2 Documentation on exports autodoc index get idxsub 2 PREDICATE No further documentation available for this predicate get idxbase 3 PREDICATE No further documentation available for this predicate typeindex 5 PREDICATE Usage typeindex Type Index IType Name Comment Description Index is the info index name in which objects of type Type go Name is the title of the index in the documentation IType is the type of index an empty string means normal codeComment is a comment to include before the index 152 The Ipdoc Documentation Generator The following properties should hold upon exit Type is currently instantiated to an atom Index is an atom IType is
50. is Ies hx onera ward 163 Library Module Index o oo oooooomo oo 165 Predicate Method Index ooo oo ooooo o o 167 Property Index x29 geht 33k Rr AX ee e 169 Regular Type Index soe tes RR E 171 Declaration Index eeoEE S a retine qx dora 173 Concept Index Ev ee EE E or ues 175 Author Index acs Joe eer ist oe RUD ET RUE eR a 177 Global Index da ER RR SCORSA AUS 179 xi Summary 1 Summary lpdoc is an automatic program documentation generator for C LP systems lpdoc generates a reference manual automatically from one or more source files for a logic program including ISO Prolog Ciao many CLP systems It is particularly useful for documenting library modules for which it automatically generates a description of the module interface However 1pdoc can also be used quite successfully to document full applications and to generate nicely formatted plain ascii readme files A fundamental advantage of using 1pdoc to document programs is that it is much easier to maintain a true correspondence between the program and its documentation and to identify precisely to what version of the program a given printed manual corresponds The quality of the documentation generated can be greatly enhanced by including within the program text e assertions types modes etc for the predicates in the program and e machine readable comments in the literate programming style The assertions and com
51. of sectioning documentation comments doc C with C one of title section and subsection Currently the section and subsection comments are still ignored by LP doc Jose Morales e Support for mathematical notation experimental new math and begin displaymath end displaymath enviro ments are supported see the documentation for more details Jose Morales In doc umentation strings single must be escaped e g math lambda Jose Morales Supported in both the texinfo and HTML using MathJax backends Jose Morales Added defmathcmd Cmd N Def and defmathcmd Cmd Def both for texinfo and HTML backends Those LPdoc commands define new mathematical environments equivalent to newcommand Jose Morales Version 2 1 2004 10 28 16 38 17 CEST Last version before moving to subversion 1 9 and 2 0 were merged 1 9 based on makefiles is deprecated e New functionality Use of doc declarations as a shorthand for comment now allowed Manuel Hermenegildo Made xdvi viewer ps viewer and xdvi zoom size be paramenters the latter since new versions of xdvi display sizes differently than old ones Manuel Hermenegildo Processing options can now be set for each file independently Manuel Hermenegildo Proper pdf generation now achieved in most cases thanks to newer versions of dvips Manuel Hermenegildo Added option c Target in Ipdoc that treats Target as a separate compo
52. of the documentation string image epsfile including an image at point contained in file epsfile The image file should be in encapsulated postscript format image epsfile width height same as above but width and height should be integers which provide a size in points to which the image will be scaled Accents and special characters The following commands can be used to insert accents and special characters Chapter 3 Documentation Mark up Language and Declarations 31 o gt 0 0 gt Q io gt o gt Q io gt 0 o 0o gt 0 gt 0 o gt u o gt 0 Qvio gt H o t oo gt 60 c o gt Q d o gt 0 Qb o gt o oe gt 0e CDE gt E Cae gt 8 CAE gt E Qaa CAA gt o gt OU gt 0 el gt L gt LE ss gt D Q gt i Q gt j i gt 1 0j gt Ccopyright iso gt Qbullet gt Oresult gt gt Usage stringcommand CO Description CD is a structure denoting a command that is admissible in strings inside assertions 32 The Ipdoc Documentation Generator version descriptor 1 REGTYPE A structure denoting a complete version description version descriptor version descriptor version Version Date version number Version ymd date Date version descriptor version Version Date Time version number Version ymd date Date time struct Time Usage version_descriptor Descriptor
53. regular types 57 6 1 Defining properties 0 0 eee hn 57 6 2 Usage and interface regtypes doc 59 6 3 Documentation on new declarations regtypes_doc 60 regtype 1 decl ia it er teo eee 60 reetype 2 decl sd Rude eC DE PER SIRE 60 7 Basic data types and properties 61 7 1 Usage and interface basic_prOpS ooo oooooooomooo 61 7 2 Documentation on exports basic_propS 0oooo oooo oo o 61 termi regtype 10 EE 61 Tit LEE arms Tes hcec UE Staa A 62 nnegint 1 r gtype ves A cos 62 Ht 1 reglyDe fessa dee oes OU ee Ce E 63 A a n a o R E Ea 63 EE EE 64 EE DEE E yo iore boe dece mL en aci is 64 E nosse e eR IER VOL NU 65 gridstE LT peli dia 65 constant l regtype i venue mn CE RR ee ee ae 66 eollable l regbype occ Eege d ees Tiu ess 66 operator specifier 1 regtype 0 oooooooo o 67 list Tes A E 67 list 2 reptvpe EE 68 e A aee a E r A e a 68 member 2 EE 69 sequence 2 regtype 00 cece eee cece eee o 69 sequence_or_list 2 regtype oooooooomoooo 70 character code 1 regtype sseesseseeess 70 sung zl eeh ce O eae 71 n m code l regtype ccce S Re 71 predname L regtype c ve get rime a 71 atm or atmlist 1 regtype ceret ied see newer 72 COMPAL PLOP ge ech EE E bore rs 72 St Prop So vd eee er Ox ia Ec e 72 SL PEO ld IES 73 deprecated prop io a DE 73 uot urth
54. source files for a logic program including ISO Prolog DEDC96 Ciao Bue95 many CLP JM94 systems It is particularly useful for documenting library modules for which it automatically generates a description of the module interface However lpdoc can also be used quite successfully to document full applications and to generate nicely formatted plain ASCII readme files A fundamental advantage of using lpdoc to document programs is that it is much easier to maintain a true correspondence between the program and its documentation and to identify precisely to what version of the program a given printed manual corresponds 1 1 Overview of this document This first part of the document provides basic explanations on how to generate a manual from a set of files that already contain assertions and comments Examples are given using the files in the examples directory provided with the 1pdoc distribution These instructions assume that lpdoc at least the executable and the library is installed somewhere in your system Installation instructions can be found in Chapter 14 Installing Ipdoc page 107 Other parts of this document provide e Documentation on the syntax and meaning of the assertions that 1pdoc uses those defined in the Ciao assertions library PBH97 PBH98 Bue98 These include comment assertions containing basically documentation text formal assertions containing properties and combined assertions e Docume
55. template sess 143 autodoc images mido hl nce E So rer DOS 161 autodoc index ost ses eb oe Ib E 151 autodoc MAN BEE 145 autodoc refsdb lesen 153 autodoc settings esee 131 autodoc state d i v A RV LAUDES 115 autodoc_StIUCtUTO orere s o mei Demie nnen ia Ken 129 autodoc texinfo creuse cesed oka E SE pala 137 B basic EE 61 C elei eh EE 25 165 E example module 2 9 v eR d Peewee 95 Generating suec pa E eed diras 15 L lpdoc examples e eee dere 89 lpdoc install errot ree one DR Rs 107 M meta PEPE dai rt eR NIS eS 87 N NATIVO EE 77 EENS enr A Ef eet ses 57 rtchecks et hea Pee ROE EE qe ete 103 U unittest o ome dida 105 166 The Ipdoc Documentation Generator Predicate Method Index Predicate Method Index A absfile for aux 3 eene 149 absfile for seubtarger i 149 absfile to relfile sess 149 all component specs 1 s esses 130 all indices 2 us lo ad bode es 120 all setting values sss slsseese 132 ascii blank lines 2 o clie kv 159 autodoc compute grefs 113 autodoc_escape_string_hook 5 127 137 139 a todoc finisSh 1 ere dS Lid 114 autodoc finish hook 1l 114 138 139 145 autodoc gen alternative 2 114 autodoc gen alternative hook 2 114 138 140 145 autodoc gen dockree b esses 113 autodoc rw command hook 4 127 137 139 145 autodoc translate doctree 3
56. the files in which the citations will be searched for All the references will appear together in a References appendix at the end of the manual If you are not using citations then select the nobiblio option on the main file which will prevent an empty References appendix from appearing in the manual Chapter 2 Generating Installing and Accessing Manuals 17 e startpage default value 1 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 odd number e papertype default value afourpaper allows select several paper sizes for the printable outputs dvi ps etc The currently supported outputs most of them inherited from texinfo are afourpaper The default usable for printing on A4 paper Rather busy but saves trees afourwide This one crams even more stuff than afourpaper on an A4 page Useful for generating manuals in the least amount of space It saves more trees afourlatex This one is a little less compressed than afourpaper smallbook Small pages like in a handbook letterpaper For printing on American letter size paper afourthesis A thesis like style De double spaced wide margins etc Useful for inserting lpdoc output as appendices of a thesis or similar document It does not save trees e Type lpdoc all to generate all the formats defined 1pdoc dvi lpdoc html lp
57. the size of argument X size metric 3 PROPERTY Meta predicate with arguments size metric goal Usage size metric Head Var Metric Description Metric is the metric of the variable Var for any approximation Chapter 8 Properties which are native to analyzers 85 size metric 4 PROPERTY Meta predicate with arguments size metric goal 7 7 Usage size metric Head Approx Var Metric Description Metric is the metric of the variable Var for the approximation Approx Currently Metric can be int 1 size 1 length 1 depth 2 and void 1 steps 2 PROPERTY steps X Y The time in resolution steps spent by any call of the form X is given by the expression Y Meta predicate with arguments steps goal Usage steps X Y Description Y is the cost number of resolution steps of any call of the form X steps 1b 2 PROPERTY steps lb X Y The minimum computation time in resolution steps spent by any call of the form X is given by the expression Y DLGHL97 LGHD96 Meta predicate with arguments steps 1b goal Usage steps 1b X Y Description Y is a lower bound on the cost of any call of the form X steps o 2 PROPERTY Meta predicate with arguments steps o goal Usage steps o X Y Description Y is the complexity order of the cost of any call of the form X steps ub 2 PROPERTY steps ub X Y The maximum computation time in resolution steps spent by any call of the form X is given
58. upon exit T is a list Usage list L Description L is a list 99 PREDICATE list 1 list 1 gnd 1 not_fails 1 PREDICATE list 1 list 1 gnd 1 not_fails 1 REGTYPE sideff 2 ground 1 eval 1 is_det 1 list 1 100 The Ipdoc Documentation Generator 11 3 Documentation on multifiles example module p 3 A general comment on the predicate The predicate is multifile The predicate is of type dynamic General properties If the following properties hold at call time Argi is ground Arg2 is a free variable Arg3 is a free variable The following properties should hold at call time foo Arg1 Arg2 is an acceptable kind of bar baz Arg3 If the following properties hold at call time Argi is an integer Arg2 is an integer Arg3 is a free variable then the following properties should hold upon exit Argi is an integer Arg2 is an integer Arg3 is ground If the following properties hold at call time Argi is an integer Arg2 is an integer Arg3 is a free variable then the following properties should hold globally All the calls of the form p Arg1 Arg2 Arg3 do not fail Usage 1 Description This mode is nice The following properties should hold at call time Argi is an integer Arg2 is an integer Arg3 is a free variable The following properties should hold upon exit Argl is an integer Arg2 is an integer
59. which is not a free variable nonvar 1 B is a free variable var 1 B is rather long long 1 The following properties should hold upon exit E is ground gnd 1 C is ground gnd 1 A is ground gnd 1 The following properties should hold globally D is not further instantiated not further inst 2 All the calls of the form t A B C D E do not fail not fails 1 Chapter 11 Auto Documenter Output for the Example Module s 1 Usage s A The following properties should hold at call time A is a list The following properties should hold upon exit Ais a list A is ground The following properties should hold globally AII the calls of the form s A do not fail q 1 Usage 1 q A Description Foo The following properties should hold at call time A is a list The following properties should hold upon exit A is a list A is ground The following properties should hold globally All the calls of the form q A do not fail Usage 2 q A Description Not a bad use at all list 1 General properties List L The following properties hold globally list L is side effect free list L If the following properties hold at call time L is currently ground it contains no variables then the following properties hold globally list L is evaluable at compile time All calls of the form list L are deterministic list T The following properties hold
60. 1 tee de WERE be Zeen assrt status 1 2 2 ed Ga AL ae e assrtcty pes Ieri ere es He RSEN atm DENG atm or atn list 1i Gee aile hale Deeds B CLASSE body EE Callable diario ii at Roce character_code l ooooooooooooo o complex arg property 1 ss eees complex goal propertu l sess constant 1 2 2 8402449 4 hee eee Lal D dictionary locaciones a A UU ENTUM WE RE TM doclink 1 ei RT RE UAR RM ES docstate 1 c uobis ues eU ede NUES doctokens 1 ive be e Rene doctree 1 ccu ees DURER IP VENE ERA F filename 1 4 htt A dida be BEES filetype il c ies kelke dE Re ahaa ees fla p values 1vX lb e ds Be E Ee CEL NAAA SI AN A G gcassrt body i i id dee di EE CEET 173 L Jist iv uus busque E A nds 67 99 list 2 i i udi ue DU LU een US 68 101 list or aorb 2 252 4 pe E eL 96 M mnodtype 1 o a RN gelu 120 N ALISTAS ute edv en End ERE ES 68 nnegint 4i 52 A MES 62 num AA Ces toe ERES RS 63 num Code 1 secu a ER eg 71 operator Specifier l 67 P predf nctor i tk Me cay pied ei ee 56 predname E TEE 71 property conjunction 1 s sess 53 property Starter 53 propf nctor ic ifs aa dee pe recs OH 56 s ssrt body l creep ere PDAs 54 BESETZEN eim wakes 154 Sequence 2 eege ae urs A pe p ape 69 sequence or Lisr eee 70 string ls ees due ET REIR ENS 71 SELUCE 1 cies ane ee ke or RR ex aee 64 s btarget 1 4 mia RR TERT 14
61. 113 B backend alt format 2 eee 117 backend ignores components 1 116 o i us teo Eat hne Ue dC 133 bind dict varnames 1 sees 120 C callm 2 9 Feed ui Re ERN Ub EE 88 check WEE 48 check Settins Litoral ed Rete 131 lean O ota tdo 149 clean_all_temporal 0 000 00s 149 clean current refs 1 ess 153 clean docs no texi 0 eee 149 clean docsttr ees 129 clean fs db O e Ze deg REIS Renee d 148 clean image cache 161 clean intermediate 0 eese 150 clean tex intermediate 0 150 cud type 1o ue RIS p ieee ee ws 123 codetype DEE 152 compute refs and biblio 1 153 convertce ic otov a e V EH aes 133 167 D doc id type 3 l sc A LI Wed wie i ue Sd 32 dociink at 2 repel ben Events 125 doclink is local 1 sees 125 docst backend cese eese 117 docst currmod 2 een 117 docst currmod is main 1 s 118 docSt gdata 3 oot sr d EE D 119 docst gdata clean t esses 119 docst_gdata_query 2 04 119 docst gdata duerg sess 119 docst gdata restoreil 119 docst gvar restore 2 cs eeeess 120 docst gvar Saue sss eene 120 docst has index 2 eee 120 docst inputfile 2 v ra 117 docst_mdata_assertz 2 119 docst mdata clean 1 c cuv NEE LU 119 docst mdata save 1
62. 117 doest backend 2 pred ic erer EA erla rete ehe 117 dotst currmod 2 pred 5 duse Ehe EE ERES 117 docst set currmod 3 pred 4 044 saved tetro 117 docst opts 2 pred ve eus 2 5 eee ete 117 docst set opts 3 pred patada ek rd Evam 117 doecst anp ttile 2 pred aicut d re eth tra 117 docst new no src 4 pre HT docst new with src 6 red 118 docst new sub 3 pred sese 118 docst message 2 pred ooooooooococommmoo 118 docst_message 3 pred 0 0 e cece eee ee 118 doost OpE 2 EE 118 docst_currmod_is_main 1 Drei 118 docst_no components 1 red 118 docst modname 2 pred ug eves erga eens 118 labgeninit 1 pred ara 118 labgen clean 1 pred oievseisqde eec reali eaten 118 labgen get 2 pred sio eier EEN EET 118 docst mvar lookup 3 pored 119 docst mvar replace 4 pred eee 119 vil docst mvar get 3 pred 4 2 erue 119 doest mdata clean 1 pred so 455404 eret 119 docst_mdata_assertz 2 red 119 doest mdat save 1 pred eee eed ents es 119 docst gdata 3 pred scettr A 119 docst gdata query 2 pred bred ee Pret E 119 docst_gdata_query 3 pred ooooocoooommm 119 docst_gdata_restore 1 pred o o oooooooo o 119 docst gdata clean l pred erede 119 docst_gvar_save 2 red 120 docst gvar restore 2 pred eee eee 120 doest has index 2 pred seres 120 allitidices 2 pred Loria oea a a 120 get doc 4 pr va 120 get doc field 3 pr
63. 15 117 docst_new_sub B3 o oooooo o 115 118 Global Index docst new with src 6 sess 115 118 docst no components 1 115 118 do st opt 2 ee ere RR EAR NEEN 115 118 docst opts 2 e o docs aster e dE eg ade 115 117 docst set currmod 3 ees 115 117 docst s t opts 3 ues da 115 117 docstate Argi o suas e arnes 153 154 docstatelArgl iii dida 126 docstate DocSt 113 126 138 139 145 157 161 docstate 1 113 115 117 126 138 139 145 153 154 157 161 docstr node 4 v da s 129 docstring 1 25 32 33 34 35 36 41 48 51 52 54 55 56 d ctokens 1 cioe ub EN bv 123 125 doctree 1 123 124 126 127 138 139 145 152 154 doctree concat 3 eese 123 124 doctree insert before section 3 123 124 doctree insert end 3 123 124 doctree is empty 1 sss 123 124 doctree prepare docst translate and write 3 uds Ute tee PARAS dia Moe au Beaute et eL 123 126 doctree Putears b sse ese 123 125 doctree restore 2 eee 123 125 doctree save 2 eee 123 125 doctree scan and save refs 2 123 126 doctree sinplifv 123 125 doctree to rawtext 3 ss 123 126 doctree translate and write 3 123 126 docum nt Structure ee a ie eee D 16 documentation format 111 documentation strings sess s 32 DOTES Cia ove Rt
64. 2 DECLARATION This assertion is similar to a test 1 assertion but it is explicitely qualified with an assertion status Non qualified test 1 assertions are assumed to have check status In this context check means that the test should be executed when the developer runs the test battery Usage AssertionStatus test AssertionBody The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is a predicate assertion body s_assrt_body 1 comp 1 DECLARATION This assertion is similar to a pred 1 assertion but it only provides information about the global execution properties of a predicate note that such kind of information is also con veyed by pred assertions The described properties might be conditioned to a particular way of calling the predicate For example the following assertion specifies that the computation of append 3 see lists will not fail if it is called as described but does not compel the predicate to be called that way comp append Xs Ys Zs var var var not fail Usage comp AssertionBody The following properties should hold at call time AssertionBody is a comp assertion body g_assrt_body 1 comp 2 DECLARATION This assertion is similar to a comp 1 assertion but it is explicitely qualified Non qualified comp 1 assertions are assumed the qualifier check Usage AssertionStatus comp AssertionBody
65. 4 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 basic props Pl imita a uu VES 103 basic Drops regtrpe i 97 basiccontrol 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 DABA ES aia e dad BACH 100 A EE 95 100 bibliographic citations 29 bibliographic entries 0 005 16 bibliographic entry sese 29 O tee Qt 11 16 29 108 bibtex 1 onic eee REY ap ont pen 131 133 bind dict varnames 1 s s 115 120 bind ins 1 EE Ee 61 63 69 75 blank Les sn ea Re E e AN 27 bold WE 27 185 C c_assrt_body 1l 43 44 46 51 54 EAT A tae EE 9 CALC A EA as 102 Call et EEN ee REN ee ee SE N 54 RER EE EE A a a 87 callable i 1 zo ee Mash den 61 66 82 87 88 Cal Ime esee erster de d Se 87 88 Calls asseftioh ees bea e AR aS 43 44 CAML S Ac wh tate cath ceat tee 42 43 44 46 A nea E EE a a aiaa 42 43 character string ares rarere p ig oo A GS 41 character code 61 70 71 check assertion iix ala b EP ET 48 Check Miri A Rv e dene va 82 check 1 2 253 454 x Rep Lb E Ee 42 48 49 check setting l c es cub 131 Ciao we Scat Sots ee ed 3 15 19 20 89 107 Ciao Emacs mode vic EeRDR E 15 Cl806 Uo Mor REN Ue eV ene y Ears 8 9 ciaodesrc makedir ConfigValues 137 Ee 77 GJpegos A ee ola eet 108 eat E E EE 147 149
66. 4 SUCCESS Lucia a 42 44 46 Success 2 cv uaque b es 42 44 supported documentation formats 113 supported file format 1 147 148 supported option sess 115 116 synopsis section of the man page 16 syntax of formatting commands 26 system 77 112 115 137 139 143 147 159 161 system modules 16 system info 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 T EE S Na NUM Ades IRA TE me 95 98 Ch ty seed setae anh aeu LES Pede IR ga tane 107 A NT 77 85 o bee vaa uu s 33 61 69 113 term basic 25 42 51 59 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 term compare 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 term typing 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 Eerginates t REENEN DRE 77 86 terms 112 115 123 129 137 141 143 147 157 161 terms never dere asse a 61 77 ee VALS EEN ee te dE EE EN eite NL 77 Global Index test dssertion c ome v have day 44 45 105 test i kie A 42 44 45 test 2 cv dil NEU Np ttle anes s 42 44 test type 2 b Ru 62 63 64 65 77 86 EE 24 108 TG T C DE E 9 tex doc uc ea RELIER oh EPA 131 133 texec asse
67. 4 io aux 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 io basic 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 18 255 0 bI RUD ML eU t P 102 is det 1 62 63 64 65 66 67 68 77 79 99 is index cmd 1 sees 151 152 is nonempty doctree 1 123 124 is version 1 9e EE 123 126 is0 1 oe INE E 10 61 73 100 italics facec i1 p AG nk d TEM uM 27 item in an itemized list 26 Itemized TTS GE 26 J Jose F Morales 111 115 123 129 131 137 139 141 143 145 147 151 153 157 159 161 K Keyboard key een pr e ales E 27 known format 1 een 161 L labgen clean ne oni nei Te t 115 118 labgen Set Ae at 115 118 labgen init l a bn dee 115 118 Dalex2 In ise etd deed t T n ep von 26 LaTeX notation is i eg ie 29 letter size pap r ooo yore A Ekana n 17 Tibraryos lai heen a ME NECEM Lass 3 library basicmodes ssssss esses 52 189 library isomodes e spree Teenie e pio 52 linear l EEN 77 80 Linux AE de o EVI 107 108 list 1 61 67 68 69 72 82 96 97 98 99 100 101 list 2 37 38 53 61 68 97 98 101 113 161 list e A ERRAT Rie 95 96 lists 42 45 77 95 112 115 123 137 139 143 145 151 153 157 159 ER Ge ET 104 literate pr
68. 6 doctree to rawtext 3 Ipored 05 126 doctree_translate_ and_write 3 pred 126 escape string 4 pred is leat os eee eee et 126 is_version 1 EE 126 version p tch 2 pred vis ses yes ees RENE cars E dS 127 versi n date 2 EEN 127 version mitnstr 2 pred 1 5 2 ir eds 127 version surmg 2 pred eer weet e rt 127 msert show toc 4 pred Srt dee 127 17 3 Documentation on multifiles autodoc_doctree 127 viii The Ipdoc Documentation Generator autodoc rw command hook 4 pred 127 autodoc escape string hook 5 pred 127 18 Handling the Document Structure 129 18 1 Usage and interface autodoc structure 129 18 2 Documentation on exports autodoc structure 129 docstr node 4 pred i43 Eo Eee eer Ee 129 cleancdocstr Dred cesis pue br d AEN Ee ER 129 parse_structure O pred ee cece ee ee eee 129 standalone docstr l pred 2 vein es 129 get mainmod 1 pred ect cer RE E 129 get mainmod spec 1 pred oooooooomommoo 130 all component specs 1 pre 130 19 Access to Default Settings 131 19 1 Usage and interface autodoc settings 131 19 2 Documentation on exports autodoc_settings 131 lpdoc_option 1 pred EE 131 verify_settings 0 pred gitt du met eR 131 check setting Ch pred e oie cae eek pe REM 131 setting value or default 2 pred sessusrusu
69. 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 exit assertion EE E ee ete UN Yir 46 AT e TEE 42 46 47 o csse seam e re eaa VO es 42 47 exported Dredicates ess 00s eee 111 GE 103 F fails 40d DABIS 77 79 false assertlon e debe wei E dues 49 Pals vene A A Y 42 49 fastformat a aria 137 139 145 file_format_name 2 147 148 file_format_provided_by_backend 3 147 148 file_utils 77 137 139 141 143 157 filename Lita as 147 Filename cio memes 112 115 129 188 fil typ i EE 25 32 38 filter 2 eh tee in Eee tm s o ves 61 75 finite solutions 1 esses 77 79 PUTO OX sie ar aden tie d S Ee alee uu 19 fixed format textual its 27 fixed width font 242 2 os Secs fa acus nes 27 Plage ah EES 61 75 flt Ti its dette ie eben neat m on 61 63 fmt html template 3 9 ee Lb Reus 143 fmt dx env T d natem unir 151 152 fmt index 3 c nem patus 151 152 fmt infodir entry 3 s 112 113 f00s cu cas arene ohn tuis auti b TV as 95 AA Manna a E A 100 footnotes s he EE 27 formatat EE 112 123 137 157 161 formatting commands 3 25 41 framed Dorai ueni lee b pex a dd UMP 27 Francisco Buens usse 41 57 77 87 func 1c soe DUC AVIS EE AE 55 G g assrt body i EE 45 51 55 generate html pointer b 7 generate_html_pointer 6 7 Generating
70. 7 61 77 89 107 111 115 123 137 145 155 157 159 P Pedro Lopes As i oe de ES ME ER 57 77 182 The Ipdoc Documentation Generator Global Index Global Index 183 This is a global index containing pointers to places where concepts predicates modes prop erties types applications etc are referred to in the text of the document ium teer mE ett mated a s mde EE 6 MOY Ds C DPI oie Sea dE eu oes Hs 69 Prop EE 88 E e Re Qo be DER aa edie aes Ee 53 Cautodoc structure e 153 BEER 16 29 EST Cox pie oh ug beste pe LN M I usq 18 e RE 18 EE 42 SY Dot eh ces SAS tn ee ed we AS 32 33 34 35 36 37 38 BOY Uus oy echo ed dE eli ghee tates 42 Q1 command ER 31 Q command EE 31 0 command usu da CR usns 31 Q0 command uere RU MERE Dua Y RE EY e 31 Q command 24 x tt RERBA MAS SOLO 31 07 command lub pee e edu Ya idee drew 31 QS command iu ry seas A 31 07 Commando svo uires sae und de oS og hata 31 Q command urere rre ECL Pr Ure ride ate t 31 Q command usuewensssteuade kie pu Reli 31 aa commando uu ele EET AE Eg 31 GAA command ria EE ie e EN 31 Qae Command iss s eu ec hne eU 31 QAE command 335 ae A oye AE 31 Qapl Commande ek E ER ERR eins 28 author commande 29 Ob Commande EA EEN d ee LU LEE RSS e 31 beginfalert commande 27 begin cartouche commande 27 begin description command 26 begin displaymath command 30 beginfenumerate comm
71. 7 T Berm 1 Lnisciziesg emt yq ale erh aere d Ae 61 time Struct 1 cs EE rl See 39 tree 0f 2 LIN ld aee te RE Ee se 96 version descriptor 1 s eesses 32 version maintenance type 1l 39 version number 1 eene 38 174 The Ipdoc Documentation Generator Declaration Index Declaration Index Calls di ERA IUS MB sus 43 calls 2 EE 43 COMO EE 48 COMP Li vnPHpix b Aran RE EUR er ree Me 45 COMPIZ ee REED RUSO ERR NERA 45 D dec ld EN E S 47 AAA A A be 47 Oe EE ere EE 32 AT E OTI Lt rie du DR IN UN E 46 E EE 46 SEET She et EN cta WS rid 47 M modedet ii Myrer at ce feta oho A 47 175 P predi ases mi abet ees ui dA LpRe ce REA 42 pred 2 s vbsvedp ier UU A eg 43 propietat did de WSO asas Me 45 pEop42 d pei OA 46 regtype i3 t o v agestbeibgU ee Spot bars 60 regtype 2 be EF epee acne P YS 60 success 1 olas oo iuo NOM esie 44 TEE 44 T A loads berre de Yaw te ee ed gu E Exe Yen 44 HA A dE A bed See A A 44 texec d icu athe ns Ades E Meque s 43 texec 2 e ib Leu crest du Rr cer euer fo Eo Mut 43 176 The Ipdoc Documentation Generator Concept Index Concept Index Ql command iii e RE xs 31 Q command 7 ev Ae le e Me E 31 Q command 2c UP HEP EAE IRR 31 EI comriand arar ere ee aa 31 Q command a a d ES EIS qus 31 Q commoaid uilns vp RIP QVIS EYE Se 31 Q command oy me RS Ee ts 31 Q command rRBhipR PRESS 31 O command xo Ee ted Ren RATS 31 Q command o
72. 80 SHOVE shes 65i e ia 104 sideff 2 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 99 101 Sideffohard 1 Lita obs c ee eas 77 83 sideff pure d ee VICEM ER RSS 77 83 sideff soft 1 u40 els eat oe heen ee 77 83 CR EE 77 83 SIA Mii ba ate se EPA 77 83 Slgnals 2 pees bebe vt uM what weet es 77 84 SAIZ EE 77 84 SiO TEE EE 77 84 SOLID DA e dis bd e 77 84 size MOE anan ae Booed Sr et he hes 77 84 Size metric 4 i X a A ds 77 84 gize EE 77 84 Le 77 84 Soft side effects 3 cscs ER ee bene eee 83 Sol tions 2 r iaa Ae AE det 77 82 SORT chives a dar aede iret EISE d 77 space extra Lines 27 spcae horizontal fill 27 special characters EN 30 ER rabia ia 41 standalone_docstr l oooooo oo 129 Steps 2 e A A 77 85 STEPS TD once were aoe aa Ae 77 85 97 The Ipdoc Documentation Generator Steps 0 2 22 57 ehh be a A IMS 77 85 Steps b 2 o ee anges it 77 85 Streams oss erp epp E RA e Ere s 77 streams_basic 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 string 1 61 71 112 116 126 143 152 154 161 stringcommand 1 25 26 48 52 54 55 56 SLIDES A a on 25 EE 27 SEU Mia tts GUN NER UY 61 64 65 s bsection g 0 ee weite x e xs 27 Subtarget list cuir tate iio Seki ee ca pelea 147 Subtitleo s l ath idad CA eee 33 success assertion ee eee eee eee 4
73. Calls of the form Goal throw a signal signal 2 PROPERTY Meta predicate with arguments signal goal Usage signal Goal E Description A call to Goal sends a signal that unifies with E 84 The Ipdoc Documentation Generator signals 2 PROPERTY Meta predicate with arguments signals goal Usage signals Goal Es Description Calls of the form Goal can generate only the signals that unify with the terms listed in Es size 2 PROPERTY Usage size X Y Description Y is the size of argument X for any approximation size 3 PROPERTY Usage size A X Y Description Y is the size of argument X for the approximation A size 1b 2 PROPERTY size lb X Y The minimum size of the terms to which the argument Y is bound is given by the expression Y Various measures can be used to determine the size of an argument e g list length term size term depth integer value etc DL93 LGHD96 Usage size lb X Y Description Y is a lower bound on the size of argument X size 0 2 PROPERTY Usage size o X Y Description The size of argument X is in the order of Y size ub 2 PROPERTY size ub X Y The maximum size of the terms to which the argument Y is bound is given by the expression Y Various measures can be used to determine the size of an argument e g list length term size term depth integer value etc DL93 LGHD96 Usage size ub X Y Description Y is a upper bound on
74. Description Descriptor is a complete version descriptor filetype 1 REGTYPE Intended uses of a file filetype module filetype user filetype include filetype package filetype part Usage filetype Type Description Type describes the intended use of a file doc_id type 3 PREDICATE No further documentation available for this predicate 3 3 Documentation on internals comments doc 2 DECLARATION This declaration provides one of the main means for adding machine readable comments to programs the other one is adding documentation strings to assertions Usage 1 doc CommentType TitleText Description Provides a title for the module library or application When generating documentation automatically the text in TitleText will be used appropriately e g in the cover page as document title or as chapter title if part of a larger document This will also be used as a brief description of the manual in on line indices There should be at most one of these declarations per module Example doc title Documentation riented Assertions The following properties should hold upon exit CommentType title 2 TitleText is a documentation string docstring 1 Usage 2 doc CommentType SubtitleText Chapter 3 Documentation Mark up Language and Declarations 33 Description Provides a subtitle an explanatory or alternate title The subtitle will be displayed under the proper title
75. E HA NEE 81 not fatrls 1 uu A eS 81 not further inst 2 cee eee 73 not mut exclusive 1 eee 82 num solutions 2 eee 82 P pe type Ti ibd iex is HERE UNA 76 possibly fails 1 5 o ve ads 82 possibly nondet 1 esses 83 PEOP eed dp E Le PATERE 8T Propabs 4 ess cys ae ERE SA EE 88 R LOCC YPC E th as ds PURI D 74 re type 2 c ono Ris RE ae le vs 88 relations 2 p Eed DA TENER ee So 83 172 S E TEE 74 sideff hard 1r ca td aa 83 sideft_pure Ladron ida 83 sidef f Softin AA oou Eau iss 83 signal 1 2 tt ahi pe xt uude pde es 83 signal 22 24 cil em RR AE DE oe 83 siguals 2 e hv ees aevi ER UL 84 S126 25 4 a At ee Ab Gok E PEL eei 84 Size 3G coke es qi sisi sevi EE Dd 84 size ID 2 EE 84 Size metric J o 32 0 0h15 m e b ER IM TES 84 Size metric 4 220204164 gne erue ES 84 A nm ld eu Le opui CE 84 size b 2 cu A TX Wen RETI 84 sSolutions 2 i A eS 82 The Ipdoc Documentation Generator Steps 2 xc rub s oh vevterpe t LE NE 85 Steps 1b 2 2 E EVE Ue ore E Ted p 85 Steps 0 2 7 2 he Rn iaie AE 85 Steps UD Boise eer RI AREE RE 85 stringcommand 1 A cup ERE 26 supported option eisiaa Ske per PEE rE na 115 T arreti DEE 85 terminates 1 2 4 2 a GE es 86 test type 2ucueni ss ERG eo IE Y pere EE 86 tlhrows 2 5 t c HL UII We Eis 86 U user outp t 2 c lip De OU RAE Ei 86 Regular Type Index Regular Type Index A AMD Dn p RE RS TN assrt body lc i2nci
76. EE IER 26 di tiesto Sek a 112 115 139 151 157 dictionary tata 51 54 Gir EE 20 107 distutils dirutils 141 143 147 distutils distutilS oooooooo 131 Loy A 19 22 23 25 32 36 38 42 47 48 doc id type 3 vice db E 25 32 docsstructure 1 bees D er NEE 16 doclabel 1 unit Ve Sade a ideas 123 125 dock dicos ia drid IIR 123 125 154 doclink at 2 ii its iaa at 123 125 doclink is local 1 72 oe DeL 123 125 docst backend sees 115 117 docst currmod 2 EN oer v A 115 117 docst currmod is main 1 115 118 docst gdata 3 isses MEER LU 115 119 docst gdata clean 115 119 docst_gdata_query 2 115 119 docst_gdata_query 3 0 115 119 docst gdata restore 1 115 119 docst_gvar_restore 2 115 120 docst gvar Saue rcu ir Wose bAt Eee ni 115 120 docst_has_index 2 o o oo o o 115 120 docst Anputfile esses 115 117 docst_mdata_assertz 2 115 119 docst_mdata_clean l 115 119 docst_mdata_save l 115 119 docst message sels 115 118 docst message i sells 115 118 docst modname 2 eee 115 118 docst modtupe esee 115 121 docst muar get 3 ssss sls 115 119 docst mvar lookup 3 sess 115 119 docst_mvar_replace 4 115 119 docst_new_no_sIC 4 1
77. ERTY call P A A has property P provided that P is a property Equivalent to P A Usage call P A Description A has property P If the following properties hold at call time P is a term which represents a goal i e an atom or a structure callable 1 88 The Ipdoc Documentation Generator prop 2 PROPERTY Usage A prop P Description A has property P If the following properties hold at call time P has property callable prop abs prop 2 regtype 2 PROPERTY Usage A regtype T Description A is of type T If the following properties hold at call time T has property regtype prop_abs prop 2 9 3 Documentation on multifiles meta_props callme 2 PREDICATE User defined A hook predicate you have to define as callme P X P X in the program that uses this library This is done automatically if the package is used instead of the library module but then you should not define callme 2 in your program The predicate is multifile Usage callme A B The following properties should hold at call time A is a term which represents a goal i e an atom or a structure callable 1 9 4 Documentation on internals meta_props prop_abs 1 PROPERTY prop_abs Prop Prop is a property abstraction i e a parametric property or a term formed of property abstractions where the functors used in the term are escaped by One particular case of property abstractions
78. PPeONGiX jee Ad Beien dree D te bI es RAE 34 application bon uw heated Mek ly Weser ec Eu 4 aritbhepression l s seeeeees 102 arithmetic 25 42 43 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 ascii blank lines 2 sees 159 assertion body syntax 51 54 55 assertion status 43 44 45 47 assertions 3 22 23 25 41 42 51 111 assertions assertions props 42 59 112 115 assertions assrt lib 112 115 assertions native props 61 95 assertions props venne 51 assrt_body 1 42 43 46 47 51 60 assrt_status 1 43 44 45 46 47 51 56 60 assrt type 1 edt Aes te ks 51 56 atm 1 oes 38 61 64 113 143 148 149 152 ati or atm listillo Me eee ee 61 72 SE vein wed esd pu I ee Ale 112 126 152 atomic_basic 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 attributes 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 Et OT 33 author ind xing 0c cece cece ees 33 a todoc vllo EE EEN VERD eee 3 16 111 autodocsaux oA ees ett aba es 159 autodoc bibretfs ccc ccc eee eee 157 autodoc_compute_grefs 3 112 113 autodoc doctree llle et eee
79. ROPERTY mshare X X contains all sharing sets JL88 MH89 which specify the possible variable occurrences in the terms to which the variables involved in the clause may be bound Sharing sets are a compact way of representing groundness of variables and dependencies between variables This representation is however generally difficult to read for humans For this reason this information is often translated to ground 1 indep 1 and indep 2 properties which are easier to read Usage mshare X Description The sharing pattern is X The following properties should hold globally This predicate is understood natively by CiaoPP as sharing X native 2 mut exclusive 1 PROPERTY mut exclusive X For any call of the form X at most one clause succeeds i e clauses are pairwise exclusive Meta predicate with arguments mut exclusive goal Usage mut exclusive X Description For any call of the form X at most one clause succeeds no choicepoints 1 PROPERTY Meta predicate with arguments no choicepoints goal Usage no choicepoints X Description A call to X does not create choicepoints Chapter 8 Properties which are native to analyzers 81 no_exception 1 PROPERTY Meta predicate with arguments no_exception goal Usage no_exception Goal Description Calls of the form Goal do not throw any exception no_exception 2 PROPERTY Meta predicate with arguments no_exception goal Usage no_exceptio
80. The lpdoc Documentation Generator An Automatic Documentation Generator for C LP Systems REFERENCE MANUAL The Ciao Documentation Series http www ciaohome org Generated Printed on 15 August 2011 Technical Report CLIP 5 97 1 3 0 Version 3 0 2011 7 7 16 33 15 CEST Edited by Manuel Hermenegildo Jos Francisco Morales Copyright c 1996 2011 Manuel Hermenegildo and Jos Francisco Morales This document may be freely read stored reproduced disseminated translated or quoted by any means and on any medium provided the following conditions are met 1 Every reader or user of this document acknowledges that is aware that no guarantee is given regarding its contents on any account and specifically concerning veracity accuracy and fitness for any purpose No modification is made other than cosmetic change of representation format translation correction of obvious syntactic errors or as permitted by the clauses below Comments and other additions may be inserted provided they clearly appear as such translations or fragments must clearly refer to an original complete version preferably one that is easily accessed whenever possible Translations comments and other additions or modifications must be dated and their au thor s must be identifiable possibly via an alias This licence is preserved and applies to the whole document with modifications and additions except for brief quotes independently of the rep
81. and 26 begin itemize command 26 begin verbatim command 27 Obf command EE 27 Obullet command LII Sa ius 31 OG Command isp cic dee it eel ant wad 31 cindex commande 28 Qcite command EN A wee te 16 29 comment commande 26 concept COMMON o o ooocooocoocoocooco oo 28 copyright commande 31 Od command ENEE EE 31 Odecl command need EE SERS Rae 28 defmathcmd 2 commande 30 defmathcmd 3 commande 30 Geni COmMANG iie LIEU npe e Eds 27 email commande 29 endfalert commande 27 end cartouche commande 27 end description command 27 end displaymath command 30 end enumerate commande 26 end itemize command 40 26 end verbatim command 04 27 Ofile Command 5 eee ak aes Slee eae A 29 footnote commande 27 OH command ik CG shee ee atk Ses ve 31 Ohfill command deet ee hes bod 27 KREE 31 image Commande 30 include commande 30 includedef command lees esses 30 includefact command 30 includeverbatim command 30 index commande 28 Giso Commands vende ds he gee ee ete ano 31 Qitem commande ee hehe NN SN enn 26 27 NEEN 31 Okey command MEET 27 Ol Command A ede es aa ee oe ele Ae edi 31 OL Command cl Sa es eh So ee ee a NL 31 184 QOlib command o cede icy a a 28 Omatlhl command 7 2 5 2
82. aoPP native 1 not mut exclusive 1 PROPERTY not mut exclusive X For calls of the form X more than one clause may succeed Le clauses are not disjoint for some call Meta predicate with arguments not mut exclusive goal Usage not mut exclusive X Description For some calls of the form X more than one clause may succeed num solutions 2 PROPERTY Usage 1 num solutions X N Description All the calls of the form X have N solutions If the following properties should hold at call time X is a term which represents a goal i e an atom or a structure callable 1 N is an integer int 1 Usage 2 num solutions Goal Check Description For a call to Goal Check X succeeds where X is the number of solu tions If the following properties should hold at call time Goal is a term which represents a goal i e an atom or a structure callable 1 Check is a term which represents a goal i e an atom or a structure callable 1 solutions 2 PROPERTY Usage solutions Goal Sols Description Goal Goal produces the solutions listed in Sols If the following properties should hold at call time Goal is a term which represents a goal i e an atom or a structure callable 1 Sols is a list list 1 possibly fails 1 PROPERTY possibly fails X Non failure is not ensured for any call of the form X DLGH97 In other words nothing can be ensured about non failure nor termination of such
83. are parametric regular type abstractions i e a parametric type functor or a escaped term formed of regular type abstractions Such abstractions are a short hand for a corresponding regular type correspondingly property For example the following abstraction list list list denotes terms of the form X Y where list X and list Y hold and also terms T such that list T holds It is equivalent to the regular type abstract type X Y list X list Y abstract type T list T Usage prop abs Prop Description Prop is a property abstraction Chapter 10 An Example Documenting a Library Module 89 10 An Example Documenting a Library Module Author s Manuel Hermenegildo A simple example of the use of 1pdoc is this manual which can be built in the doc directory of the lpdoc distribution Other examples of manuals generated using lpdoc can be found in the Ciao system and preprocessor doc directories i e most of the Ciao manuals are generated using lpdoc Some simpler examples can be found in the examples directory of the 1pdoc distribution In particular the chapter following this one contains the documentation generated automatically for the module defined by file examples example module pl which for simplic ity contains only assertions i e no actual code and which is included in source form below Comparing this code with the output in the following chapter illustrates the use and some of the capabil
84. artS 2 8 6 Documenting reexported predicates 2 8 7 Separating the documentation from the source file 2 8 8 Generating auxiliary files e g READMEs 2 9 Troubleshooting x dida A ee ened AE 3 Documentation Mark up Language and Declarations EE 3 1 Usage and interface comments vespide 3 2 Documentation on exports Leomentsl sees docstring 1 prop S ee vere O stringcommand 1 prop apra version descriptor 1 regtype ooooo o filetypes eege ni EE EP ERG d id type 3 Pre gaere 3 3 Documentation on internals Ieommentsl suus Gemeen etie e aite dora eRe ee version number 1 regtype ooooooooomoooo ymd date 1 Testy EE ii The lpdoc Documentation Generator time struct 1 regtype coccion bee E 39 version maintenance type 1 regtype 39 4 The Ciao assertion package sese 41 Sech Mor O e sott umi uui E a a d 41 4 2 Some attention points 41 4 3 Usage and interface assertions doc 42 4 4 Documentation on new declarations assertions_doc 42 pred ML d cl errar ia Eech 42 EE RE 43 texec P T deel 215 sz oeste RC OR ERO n 43 Lexec a deel Lo sn EE em a oa ws 43 calls l decl ca ds ones bel See pente 43 EE EE 43 success 1 decl eg tdi ved eviter er ted 44 success 2 dec usc Age ke xA SIR PEE 44 EE 44 test 2 deel secre oe ey ey wet eae ese E 44 comp deel NEE ear ei 45 comip dec EE 45 propc
85. ary components are also libraries This can be used for example for generating an internals manual of a library The main file describes the purpose and use of the library while the components describe the internal modules of the library e Main file is an application components are libraries This can be used similarly for gener ating an internals manual of an application The main file describes the purpose and use of the application while the components describe the internal modules which compose the application e Main file is a pseudo application components are libraries A manual of a complex library made up of smaller libraries for example the Prolog library The pseudo application file contains the introductory material title version etc Each chapter describes a particular library e Main file is a pseudo application components are applications This can be used to gen erate a manual of a set of applications e g a set of utilities The pseudo application file contains the introductory material title version etc Each chapter describes a particular component application 2 8 4 Documenting files which are not modules Sometimes it is difficult for 1pdoc to distinguish include files and Ciao packages from normal user files i e normal code files but which are not modules The distinction is important because the former are quite different in their form of use they are loaded via include 1 or use package 1 d
86. at most one of these declarations per module Example doc copyright Copyright 2001 FSF The following properties should hold upon exit CommentType copyright 2 CopyrightText is a documentation string docstring 1 Usage 9 doc CommentType SummaryText Description Provides a brief global explanation of the application or library The text in SummaryText will be used as the abstract for the whole manual There should be at most one of these declarations per module Ezample doc summary This is a bf very important library The following properties should hold upon exit CommentType summary 2 SummaryText is a documentation string docstring 1 Usage 10 doc CommentType CommentText Description Provides the main comment text for the module or application When generating documentation automatically the text in CommentText will be used as the introduction or main body of the corresponding chapter or manual There should be at most one of these declarations per module CommentText may use sections if substructure is needed Example doc module This module is the Clib comments library The following properties should hold upon exit CommentType module 2 CommentText is a documentation string docstring 1 Usage 11 doc CommentType ComnentText Description Provides additional comments text for a module or application When generat
87. ate defines the different types of syntax admissible in the bodies of comp 1 assertions The following are admissible Pr CP GP CO Pr CP GP Pr GP CO Pr GP where e Pr is a head pattern head_pattern 1 which describes the predicate or property and possibly gives some implicit call answer information e CP is a possibly empty complex argument property complex_arg_property 1 which applies to the calls to the predicate e GP contains possibly empty complex goal property complex goal property 1 which applies to the whole execution of a call to the predicate These only apply if the possibly empty properties given for calls in the assertion hold e CO is a comment string docstring 1 This comment only applies if the possibly empty properties given for calls in the assertion hold The usual formatting com mands that are applicable in comment strings can be used see stringcommand 1 The format of the different parts of the assertion body are given by n_assrt_body 5 and its auxiliary types Usage g_assrt_body X Description X is a comp assertion body 56 The Ipdoc Documentation Generator assrt status 1 REGTYPE The types of assertion status They have the same meaning as the program point asser tions and are as follows assrt status true assrt status false assrt status check assrt status checked assrt status trust Usage assrt status X Description X is an acceptable status
88. ations as mentioned in Section 2 2 Generating a manual page 15 The easiest fix is to reduce the number of indices generated Alternatively it may be possible to recompile your local tex texinfo installation with a higher number of indices e Missing links in info files a section which exists in the printed document cannot be accessed in the on line document can be due to the presence of a colon a comma a double dash or other such separators in a section name Due to limitations of info section names cannot contain these symbols e Menu listings in info which do not work i e the menu listings are there but they cannot be followed see if they are indented In that case it is due to an itemize or enumerate which was not closed Chapter 3 Documentation Mark up Language and Declarations 25 3 Documentation Mark up Language and Declarations Author s Manuel Hermenegildo This defines the admissible uses of the doc 2 declaration which is used mainly for adding machine readable comments to programs the formatting commands which can be used in the text strings inside these comments and some related properties and data types These declarations are ignored by the compiler in the same way as classical comments Thus they can be used to document the program source in place of or in combination with the normal comments typically inserted in the code by programmers However because they are more structured and they are
89. ations per module In order for author indexing to work properly please use one author declaration per author If more explanation is needed who did what when etc use an acknowledgements comment Example doc author Alan Robinson The following properties should hold upon exit CommentType author 2 AuthorText is a documentation string docstring 1 Usage 6 doc CommentType Text Description Provides the physical and electronic address or any other contact infor mation for the authors of the module or application Example doc address Syracuse University The following properties should hold upon exit CommentType address 2 Text is a documentation string docstring 1 34 The Ipdoc Documentation Generator Usage 7 doc CommentType AckText Description Provides acknowledgements for the module If present when generating documentation for the module automatically the text in AckText will be placed in the corresponding chapter or section There can be only one of these declarations per module Example doc ack Module was written by Alan but others helped The following properties should hold upon exit CommentType ack 2 AckText is a documentation string docstring 1 Usage 8 doc CommentType CopyrightText Description Provides a copyright text This normally appears somewhere towards the beginning of a printed manual There should be
90. b files using bibtex and produces a References appendix cite can be used in the text strings exactly as ite in LaTeX The set of bib files to be used is given in the SETTINGS file Defining the type of version maintenance that should be performed by the emacs ciao el mode i e whether version numbers are in a given directory or in the file itself is controlled now via a standard commment 2 declaration You should now write a declaration such as comment version_maintenance dir version to state that control info is kept in directory version This has the advantage that it is shorter than the previous solution and that Ipdoc can read this info easily Using this guarantees that the version numbers of the manuals always concide with those of the software Generation of indices of manuals htmlbullet files if several manuals are installed in the same directory an index to them is now generated at the beginning of the html cover page describing the directory Manuel Hermenegildo Version 1 4 1998 8 4 19 10 35 MET DST The set of paths defined in SETTINGS for finding the source files are now also used to find included files As a result full path is not needed any more in e g include command New ref command which can be used to refer to chapeter sections subsections etc Support for recent minor changes in assertion format including as comment separator Used modules are now separa
91. ble then the following properties hold globally callable T is evaluable at compile time All calls of the form callable T are deterministic callable T ground 1 eval 1 is_det 1 gndstr 1 native 1 REGTYPE sideff 2 nonvar 1 eval 1 is_det 1 constant 1 REGTYPE sideff 2 nonvar 1 eval 1 is_det 1 Chapter 7 Basic data types and properties 67 The following properties hold upon exit T is currently a term which is not a free variable nonvar 1 Usage callable T Description T is a term which represents a goal i e an atom or a structure operator specifier 1 REGTYPE The type and associativity of an operator is described by the following mnemonic atoms xfx Infix non associative it is a requirement that both of the two subexpressions which are the arguments of the operator must be of lower precedence than the operator itself xfy Infix right associative only the first left hand subexpression must be of lower precedence the right hand subexpression can be of the same precedence as the main operator yfx Infix left associative same as above but the other way around fx Prefix non associative the subexpression must be of lower precedence than the operator fy Prefix associative the subexpression can be of the same precedence as the operator xf Postfix non associative the subexpression must be of lower precedence than the opera
92. c_finish_hook 1 autodoc_gen_alternative_hook 2 e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc settings lpdocsrc src autodoc filesystem lpdocsrc src autodoc structure lpdocsrc src autodoc_doctree lpdocsrc src autodoc_refsdb lpdocsrc src autodoc_parse lpdocsrc src autodoc index lpdocsrc src comments lpdocsrc src autodoc html resources lpdocsrc src autodoc texinfo System library modules format ttyout aggregates read make make_rt dict compiler compiler assertions assrt_lib compiler c_itf assertions assertions_props messages filenames lists terms make system_ extra system Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 15 2 Documentation on exports autodoc index comment 2 PREDICATE Usage index comment Index Text Description Type is a type of index which is supported Text describes the index contents The following properties should hold upon exit Index is currently instantiated to an atom atom 1 Text is a string a list of character codes string 1 reset output dir db 0 PREDICATE No further documentation available for this predicate Chapter 15 Documentation Generation Library 113 ensure output
93. ccess 1 1150 fx success 2 1150 xfx test 1 1150 fx test 2 1150 xfx texec 1 1150 fx texec 2 1150 xfx comp 1 1150 fx comp 2 1150 xfx entry 1 1150 fx exit 1 1150 fx exit 2 1150 xfx e New declarations defined pred 1 pred 2 texec 1 texec 2 calls 1 calls 2 success 1 success 2 test 1 test 2 comp 1 comp 2 prop 1 prop 2 entry 1 exit 1 exit 2 modedef 1 dec1 1 dec1 2 doc 2 comment 2 e Other modules used System library modules assertions assertions props Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 4 4 Documentation on new declarations assertions doc pred 1 DECLARATION This assertion provides information on a predicate The body of the assertion its only argument contains properties or comments in the formats defined by assrt_body 1 More than one of these assertions may appear per predicate in which case each one represents a possible mode of use usage of the predicate The exact scope of the usage is defined by the properties given for calls in the body of each assertion which should thus distinguish the different usages intended All of them together cover all possible modes of usage For example the following assertions describe all the and the only modes of usage o
94. clean all temporal 0O 147 149 clean current refs 1 ess 153 clean docs no texi 0 sess 147 149 clean docstr O sese ee 129 clean fs db O NEEN ANN ek 147 148 clean image cache 161 clean intermediate 0 s 147 150 clean tex intermediate 0 147 150 CLAU vu sonet chi al we aie x TET 77 a ET DEE 77 78 CLP Ae pata EE tle ee ee e Bede 3 CMA type DEE 123 codetype l gek ELVAI 151 152 eh GEET 26 comment assertion 02 eee eee eee eee 48 comment String l4 Ri a ae 52 54 55 COMME Dire rd eee 10 42 48 comments ts a EE 3 23 25 comments machine readable Al CommentType ack esses 34 CommentType address esses 33 CommentType appendix sese 35 CommentType author esee 33 186 CommentType bug lesen 36 CommentType copyright esee 34 CommentType doinclude oo 3T Comment Tepec filetepe sese 38 Comment Tepechide esee eee 37 38 CommentType logo seen 33 CommentType module sese eee eee 34 CommentType nodoc eese 38 CommentType section sees 35 Comment Tvpecpubsection eee 35 Comment Tvpec subtitle sese 33 CommentType subtitle extra 33 CommentType summary see 34 Comment Tvpectitle esses 32 CommentType usage eee 35 CommentType version maintenance 3T COMMENT 2 s x oppor t
95. ctly from the texi file using the texi2html command this again can be changed in the Makefile skel file in the lib directory This command is a perl script and is included with the lpdoc distribution and installed in the library so that it does not overwrite other existing versions It is also typically included in the Texinfo distribution A required intermediate step is to resolve the link references which appear in the texi file the texi file includes all the texic files and has all references resolved This is done using the emacs editor in batch mode calling functions in the emacs library el file included in the lib directory of the 1pdoc distribution Thus a recent version of emacs is required for this purpose Generating info files info files are also generated directly from the texi file using the makeinfo command this again can be changed in the Makefile skel file in the lib directory This command is included in the Texinfo distribution Resolving the link references in the texi file is also required as above If pictures are used in the manual and html output is selected the commands pstogif and cjpeg are also required in order to convert the figures from eps to jpg format PART II LPdoc Internals Manual PART II LPdoc Internals Manual 109 110 The Ipdoc Documentation Generator Chapter 15 Documentation Generation Library 111 15 Documentation Generation Library Author s Manuel Hermenegil
96. d i e once they hold they will keep on holding in every state accessible in forwards execution There are certain predicates which are inherently instantiation checks and should not be used as compatibility properties nor appear in the definition of a property that is to be used with compat Examples of such predicates for Prolog are ground nonvar integer atom gt etc as they require a certain instantiation degree of their arguments in order to succeed In contrast with properties of execution states properties of computations refer to the entire execution of the call s that the assertion relates to One such property is for example not_ fail 1 note that although it has been used as in comp append Xs Ys Zs not_fail it is in fact read as not_fail append Xs Ys Zs see assertions props complex goal property 1 For this property which should be interpreted as execution of the predicate either succeeds at least once or loops we can use the following predicate not fail 1 for run time checking not fail Goal if call Goal true then warning Goal else where the warning 1 library predicate simply prints a warning message In this simple case implementation of the predicate is not very difficult using the non standard if 3 builtin predicate present in many Prolog systems However it is not so easy to code predicates which check other properties of the computation and we may in general need to prog
97. d 2 docst_currmod 2 docst_set_currmod 3 docst_ opts 2 docst_set_opts 3 docst_inputfile 2 docst_new_no_src 4 docst_new_ with_src 6 docst_new_sub 3 docst_message 2 docst_message 3 docst_opt 2 docst_currmod_is_main 1 docst_no_components 1 docst_modname 2 labgen_ init 1 labgen_clean 1 labgen_ get 2 docst_mvar_lookup 3 docst_mvar_replace 4 docst_mvar_get 3 docst_ mdata clean 1 docst mdata assertz 2 docst mdata save 1 docst_gdata 3 docst gdata query 2 docst gdata query 3 docst gdata restore 1 docst gdata clean 1 docst gvar save 2 docst gvar restore 2 docst has index 2 all indices 2 get doc 4 get doc field 3 get doc field dict 3 bind dict varnames 1 get mod doc 3 docst_modtype 2 get first loc for pred 3 Properties supported option 1 Regular Types backend_id 1 docstate 1 modtype 1 e Other modules used Application modules lpdocsrc src autodoc settings lpdocsrc src autodoc filesystem lpdocsrc src autodoc structure lpdocsrc src autodoc doctree lpdocsrc src autodoc refsdb lpdocsrc src autodoc_parse lpdocsrc src autodoc index lpdocsrc src comments System library modules make make rt dict compiler compiler assertions assrt lib compiler c itf assertions assertions props messages filenames lists terms make system_ extra write read system aggregates nternal engine modules term basic arithmetic atomic basic attributes basic props basiccontro
98. d at call time PropertyConjunction is either a term or a conjunction of terms The main functor and arity of each of those terms corresponds to the definition of a property The first argument of each such term is a variable which appears as a head argument property conjunction 1 true 1 PREDICATE Usage true PropertyConjunction Description This assertion is identical syntactically to a check 1 assertion However the properties stated have been proved to hold by the analyzer Thus these assertions often represent the analyzer output The following properties should hold at call time PropertyConjunction is either a term or a conjunction of terms The main functor and arity of each of those terms corresponds to the definition of a property The first argument of each such term is a variable which appears as a head argument property conjunction 1 false 1 PREDICATE Usage false PropertyConjunction Description This assertion is identical syntactically to a check 1 assertion However the properties stated have been proved not to hold by the analyzer Thus these assertions often represent the analyzer output The following properties should hold at call time PropertyConjunction is either a term or a conjunction of terms The main functor and arity of each of those terms corresponds to the definition of a property The first argument of each such term is a variable which appears as a head argument proper
99. dicate requested file formats 1 Usage requested file formats F Description F is a requested file format load vpaths 0 No further documentation available for this predicate viewer 3 No further documentation available for this predicate xdvi 1 No further documentation available for this predicate xdvisize 1 No further documentation available for this predicate pdfview 1 No further documentation available for this predicate PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE Chapter 19 Access to Default Settings psview 1 No further documentation available for this predicate htmlview 1 No further documentation available for this predicate bibtex 1 No further documentation available for this predicate tex 1 No further documentation available for this predicate texindex 1 No further documentation available for this predicate dvips 1 No further documentation available for this predicate ps2pdf 1 No further documentation available for this predicate makeinfo 1 No further documentation available for this predicate makertf 1 No further documentation available for this predicate rtftohlp 1 No further documentation available for this predicate convertc 1 No further documentation available for this predicate 133 PREDICATE PREDICATE PREDICATE PREDICATE
100. directory of emacs info manuals The following properties should hold at call time docstate DocSt docstate 1 Version is any term term 1 Mod is the base name of a file without extension basename 1 autodoc_compute_grefs 3 PREDICATE Usage Description Compute the globally resolved references including bibliography 114 The Ipdoc Documentation Generator autodoc translate doctree 3 PREDICATE Usage Description Translate the doctree using the specific backend autodoc finish 1 PREDICATE No further documentation available for this predicate autodoc_gen_alternative 2 PREDICATE No further documentation available for this predicate 15 3 Documentation on multifiles autodoc autodoc finish hook 1 PREDICATE No further documentation available for this predicate The predicate is multifile autodoc gen alternative hook 2 PREDICATE No further documentation available for this predicate The predicate is multifile Chapter 16 Internal State for Documentation Generation 115 16 Internal State for Documentation Generation Author s Manuel Hermenegildo Jose F Morales This module defines the internal state of the documentation generation for a single module 16 1 Usage and interface autodoc state v S e Library usage use module library autodoc state e Exports Predicates option_comment 2 backend_ignores_components 1 backend_alt_format 2 top_ suffix 2 docst_backen
101. do Jose F Morales This library provides some predicates which generate documentation automatically for a given module or application using the declarations and assertions used in the module itself as input see the assertions library By default only the exported predicates of the module appear in the documentation The predicates will be documented in the order in which they appear in the module 1 or module 2 declaration The idea of this package is on one hand to reuse the information present in the assertions and on the other to help ensure that code and documentation are kept as coherent as possible Hopefully keeping them close together should help in this always difficult task The resulting documentation is somewhat rigidly structured but generally sufficient for a reference manual provided a little effort is put into the assertions and comments The end product understandably depends heavily on how much work is put into adding additional comments to the source Some documentation will be generated in any case but it is recommended that at the minimum a module title and a comment for each of the exported predicates be provided Note This part is obsolete JFMC The output format in which the documentation is generated is defined by the backend modules autodoc_texinfo autodoc html autodoc man etc The main output format supported is texinfo see The GNU Texinfo Documentation System manual for more info from w
102. doc ps or lpdoc info etc will force the generation of a single target format 2 3 Working on a manual In order to speed up processing while developing a manual it is recommended to work by first generating a dvi version only i e by typing lpdoc dvi The resulting output can be easily viewed by tools such as xdvi which can be started by simply typing 1pdoc view Note that once an xdvi window is started it is not necessary to restart it every time the document is reformatted 1pdoc dvi since xdvi automatically updates its view every time the dvi file changes This can also be forced by typing R in the xdvi window The other formats can be generated later once the dvi version has the desired contents 2 4 Cleaning up the documentation directory lpdoc can also take care of tidying up the directory where the documentation is being generated e lpdoc clean deletes all intermediate files but leaves the targets De the ps dvi ascii html etc files as well as all the generated texic files e lpdoc distclean deletes all intermediate files and the generated texic files leaving only the targets De the pe dvi ascii html etc files This is the option normally used when building software distributions in which the manuals come ready made in the distribution itself and will not need to be generated during installation e lpdoc docsclean deletes all intermediate files and the generated targets but leaves the texic f
103. e Chapter 16 Internal State for Documentation Generation backend alt format 2 Usage backend alt format Id Ext 117 PREDICATE Description Ext is an alternative file format that can be generated by the backend Id top_suffix 2 Usage top_suffix FileFormat PrincipalExt PREDICATE Description PrincipalExt is extension of the target file that will generate the file with FileFormat extension docstate 1 A regular type defined as follows docstate docstate Backend Name Opts MVarDic 1 backend_id Backend atom Name list Opts supported_option dictionary MVarDic filename I docst_backend 2 No further documentation available for this predicate docst currmod 2 No further documentation available for this predicate docst set currmod 3 No further documentation available for this predicate docst_opts 2 No further documentation available for this predicate docst_set_opts 3 No further documentation available for this predicate docst_inputfile 2 No further documentation available for this predicate REGTYPE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE 118 The Ipdoc Documentation Generator docst new no src 4 PREDICATE No further documentation available for this predicate docst new with src 6 PREDICATE No further documentation available for this predicate docst new sub 3 PREDICATE No further documentation available f
104. e string 4 is version 1 version patch 2 version date 2 version numstr 2 version string 2 insert show toc 3 Regular Types doctree 1 doclink 1 doclabel 1 doctokens 1 Multifiles autodoc_rw_command_hook 4 autodoc_escape_string_hook 5 e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc refsdb lpdocsrc src autodoc index lpdocsrc src autodoc structure lpdocsrc src autodoc filesystem lpdocsrc src autodoc settings lpdocsrc src comments lpdocsrc src autodoc texinfo lpdocsrc src autodoc man lpdocsrc src autodoc htm1 System library modules write operators format lists nake system extra read terms make make rt Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 17 2 Documentation on exports autodoc_doctree cmd type 1 PREDICATE No further documentation available for this predicate 124 The Ipdoc Documentation Generator doctree 1 Usage Description Intermediate tree representation for documentation doctree is empty 1 Usage doctree is empty R Description Emptiness test The following properties should hold at call time Intermediate tree representation for documentation is nonempty doctree 1 Usage is nonempty doc
105. e Type lpmake install This should install it in the BINDIR directory install the 1pdoc library in a separate directory in the LIBDIR directory and install the 1pdoc documentation in the DOCDIR directory e In order for the lpdoc documentation to be available to users automatically certain environment variables have to be set The installation leaves files suitable for inclusion in initialization scripts e g DOTcshrc for csh in the 1pdoc library 14 2 Other software packages required Ipdoc The most basic functionality of 1pdoc generating manuals in texi format short manual entries in manl format generating index files is essentially self contained However using the full capabilities of 1pdoc requires having several other software packages installed in the system Fortunately all of these packages are public domain software and they will normally be already installed in e g a standard Linux distribution It should be relatively easy to get and install the required packages in other Unix like packages or even in Windows under the Cygwin environment e Basic requirements the Makefiles used by lpdoc require GNU Make gmake and for now have only been designed for UN X like operating systems 108 The Ipdoc Documentation Generator Generating dvi files 1pdoc normally generates texi files actually a number of texic files From the texi files dvi files are generated using the standard tex package di rectly The dv
106. e database or the collection whether alone or in relation with other documents Any incompatibility of the above clauses with legal contractual or judiciary decisions or con straints implies a corresponding limitation of reading usage or redistribution rights for this document verbatim or modified Table of Contents SUMMALY eva EE ee ee vod ei e oS LL Introduction EE 1 1 Overview of this document 1 2 lpdoc operation source and target Dies L Ilpdo usage eae RR ee Ur ERE V 1 4 Version C ange LOs ec ee x PART I LPdoc Reference Manual 2 Generating Installing and Accessing Manuals 2 1 Generating a manual from the Ciao Emacs mode 2 2 Generating a manual 2 3 Working on a manual eese 2 4 Cleaning up the documentation directory ssssuueresss 2 5 Installing a generated manual in a public area 2 6 Enhancing the documentation being generated 2 7 Accessing on line manual 2 7 1 Accessing html mamals 2 ee eee 2 7 2 Accessing info manual 2 7 3 Accessing man manual 2 7 4 Putting it all together 2 8 Some usage Ups 2 8 1 Ensuring Compatibility with All Supported Target ere 2 eR teat has T RR Pe wns ES 2 8 Writing comments which document version patch ch npes ENEE EE be RES Sead RER AN 2 8 3 Documenting Libraries and or Applications 2 84 Documenting files which are not modules 2 8 5 Splitting large documents into p
107. e eee EE Ba eed 31 OL command erdre eet Ee ER ies 31 Olib command ie Tee BS ED 28 math commande 29 noindent commande 27 Qo commana Ai ida RAM Ed A 31 DCH command ti see Goa ERREUR RUPEM 31 Qoe command vesc ENN Maw ene rb Y 31 QOE commande 31 Qop command EE 28 Qp commande 27 pred commande 28 Qref command cs NET Me ee ES 29 result commande 31 section commande 27 Dep commande 27 QOss command ib ROAEIEeen DER i E de dds 31 subsection commande 27 E e e DEE 31 today commande 29 Qtt command uou x rM el PEE 27 Qi COMMAN EE 31 Quref commande 29 Qv command EE 31 Qvar Commande 29 version commande 29 178 AA paper cc uoce rimi na d ER utes 17 abstract Mam 34 ee 30 acceptable mode 52 acknowledgements eee 34 address ii ENEE 33 appendix orton E Asa ties bai 34 application way bat e v eps Cd iR qu 4 assertion body syntax 51 54 55 ASS cues ege bue e ele paris 25 author i ss yo mun TRUE Cb Mercer etd 33 automatic documentation 111 automatic documentation library 111 avoiding indentation lisse 27 B bibliographic citations sse 29 bibliographic entries o 16 bibliographic entre 29 bibtex set reple eneH hh 4 EHE Ue 16 29 blank lines eub dd AE 27 bold fate asii oa 27 DUE td AA uiam 36 calls assertion lessen 43 44 check assertion 00 0 eee eee cece eee eee 48 Ciao tase ladies As teed te de SA ES 15 COMME by ii A A ek e 26 comment ass
108. e format provided by backend Ext Backend Subtarget Description Backend is the backend that generates files with format Ext Call and exit should be compatible with Ext is an atom atm 1 Backend is a supported backend backend id 1 Subtarget is an atom atm 1 clean fs db 0 PREDICATE Usage Description Clean the cached information for the filesystem mapping of the docu mentaton generation get output dir 2 PREDICATE Usage get_output_dir Backend Dir Description Obtain the Dir directory where final documentation files will be stored get cache dir 2 PREDICATE Usage get cache dir Backend Dir Description Obtain the Dir directory where final documentation files will be stored ensure output dir 1 PREDICATE No further documentation available for this predicate ensure cache dir 1 PREDICATE No further documentation available for this predicate Chapter 25 Filesystem Abstraction 149 main absfile in format 2 PREDICATE Usage main absfile in format Ext File Description File is the absolute file name for the documentation in Ext format of the main module main absfile for subtarget 3 PREDICATE No further documentation available for this predicate absfile for aux 3 PREDICATE Usage absfile for aux AuxName Backend AbsFile Description Absolute file for an auxiliary output file e g CSS images etc absfile for subtarget 4 PREDICATE No further documentati
109. e given property in the sense that assuming that imposing that property on the term does not render the store inconsistent For example terms X i e a free variable Y Z and Y Z are all compatible with the regular type list 1 whereas the terms f a and 112 are not Meta predicate with arguments compat pred 1 General properties compat Term Prop If the following properties hold at call time Term is currently ground it contains no variables ground 1 Prop is currently ground it contains no variables ground 1 then the following properties hold globally compat Term Prop is evaluable at compile time eval 1 Usage compat Term Prop Description Term is compatible with Prop Chapter 7 Basic data types and properties T3 inst 2 PROPERTY Meta predicate with arguments inst pred 1 General properties inst Term Prop The following properties hold globally inst Term Prop is side effect free sideff 2 inst Term Prop If the following properties hold at call time Term is currently ground it contains no variables ground 1 Prop is currently ground it contains no variables ground 1 then the following properties hold globally inst Term Prop is evaluable at compile time eval 1 Usage inst Term Prop Description Term is instantiated enough to satisfy Prop iso 1 PROPERTY Meta predicate with arguments iso goal General properties iso G The followi
110. e performs analyisis Usage int T Description T is an integer The following properties hold globally This predicate is understood natively by CiaoPP nnegint 1 The type of non negative integers i e natural numbers General properties nnegint T The following properties hold globally nnegint T is side effect free nnegint T If the following properties hold at call time T is currently a term which is not a free variable then the following properties hold globally nnegint T is evaluable at compile time nnegint T The following properties hold upon exit T is a non negative integer sideff 2 nonvar 1 eval 1 is_det 1 int 1 Required by the nonfailure test_type 2 native 1 REGTYPE sideff 2 nonvar 1 eval 1 nnegint 1 Chapter 7 Basic data types and properties The following properties hold globally Indicates the type of test that a predicate performs analyisis Usage nnegint T Description T is a non negative integer The following properties hold globally This predicate is understood natively by CiaoPP flt 1 63 Required by the nonfailure test_type 2 native 1 REGTYPE The type of floating point numbers The range of floats is the one provided by the C double type typically 4 9e 324 1 8e 308 plus or minus There are also three spe cial values Infinity either positive or negative rep
111. e tabs in Tex is now run in nonstopmode which means it will typically not stop if there are minor errors but some errors may go unnoticed The full path of the version maintenance directory is now computed correctly using the directory of the p1 file being documented as base Notices for missing subtitle copyright and summary now only given from main file and not for components Chapter 1 Introduction 11 Version 1 7 Version 1 6 Version 1 5 e Added special handling of regtype and generalized it to handle some props specially if there is a certain comp property present Manuel Hermenegildo 1998 12 2 17 43 50 MET Major port to use the ciao 0 8 modular assertion processing library Manuel Hermenegildo 1998 9 8 12 49 26 MEST Added support for inserting images eps files in text via Cimage command email addresses via Cemail command and url references via uref command Unix man output much improved Also it now includes a usage section The correspoding text must be given in a string contained in the first argument of a fact of the usage message 1 predicate which appears in the program Also formatting of man pages has been greatly improved A new ascii format is now supported a simple minded ascii manual basically an info file without pointers Manuel Hermenegildo 1998 8 23 20 30 32 EST Now supporting a cite command YES It automatically accesses the bib entries in bi
112. e term but with one more argument added at the beginning which is a new variable which in a rewriting of the head pattern appears at the argument position occupied by the term For example the head pattern p Input list int Qutput is valid for mode 1 defined in library isomodes and equivalent in this case to having the head pattern p Input A 0utput and stating that the property list A int holds for the calls of the predicate Di e Any term preceded by a mode In this case only one variable is admitted it has to be the first argument of the mode and it represents the argument po sition Le it plays the role of the new variable mentioned above Thus no rewriting of the head pattern is performed in this case For example the head pattern p Input Parameter list int Output is valid for mode 2 defined in library isomodes and equivalent in this case to having the head pattern p Input Parameter Qutput and stating that the property list Parameter int holds for the calls of the predicate Usage head pattern Pr Description Pr is a head pattern Chapter 5 Types and properties related to assertions 53 complex arg property 1 REGTYPE complex arg property Props Props is a possibly empty complex argument property Such properties can appear in two formats which are defined by property conjunction 1 and property starterm 1 respectively The two formats can be mixed provided they are not in the same f
113. eclarations instead of ensure 1oaded 1 and effect since they are included they export operators declarations etc and should typically be documented differently There is a special doc 2 declaration doc filetype which provides a way of defining the intended use of the file This declaration is normally not needed in modules include files or packages but should be added in user files i e those meant to be loaded using ensure loaded 1 Adding this declaration will for example avoid spurious documentation of the declarations in the assertions package themselves when this package is included in a user file 2 8 5 Splitting large documents into parts As mentioned before in 1pdoc each documented file each component corresponds to a chapter in the generated manual In large documents it is sometimes convenient to build a super structure of parts each of which groups several chapters There is a special value of the Chapter 2 Generating Installing and Accessing Manuals 23 second argument of the doc filetype declaration mentioned above designed for this purpose The special filetype value part can be used to flag that the file in which it appears should be documented as the start of one of the major parts in a large document In order to introduce such a part a pl file with a declaration doc filetype part should be inserted in the sequence of files that make up the components variable of the SETTINGS p1 f
114. ed X For any call of the form X there is at least one clause whose test succeeds i e all the calls of the form X are covered DLGH97 Usage covered X Description All the calls of the form X are covered covered 2 PROPERTY covered X Y All variables occuring in X occur also in Y Usage covered X Y Description X is covered by Y The following properties hold globally This predicate is understood natively by CiaoPP native 1 exception 1 PROPERTY Meta predicate with arguments exception goal Usage exception Goal Description Calls of the form Goal throw an exception Chapter 8 Properties which are native to analyzers 79 exception 2 PROPERTY Meta predicate with arguments exception goal Usage exception Goal E Description Calls of the form Goal throw an exception that unifies with E fails 1 PROPERTY fails X Calls of the form X fail Meta predicate with arguments fails goal Usage fails X Description Calls of the form X fail The following properties hold globally This predicate is understood natively by CiaoPP native 1 finite_solutions 1 PROPERTY finite solutions X Calls of the form X produce a finite number of solutions DLGH97 Meta predicate with arguments finite solutions goal Usage finite solutions X Description All the calls of the form X have a finite number of solutions have choicepoints 1 PROPERTY Meta predicate with argum
115. edio das e e er ie he d 120 get doc field dict 3 pred ooooooooooo o 120 bind dict varnames 1 pred 000005 120 get mod doc 3 e EE 120 modtype 1 regtype 00 cee e eee eee eens 120 docst modtype 2 pred voceros iara 121 get first loc for pred 3 pred 2 121 17 Documentation Abstract Syntax Tree 123 17 1 Usage and interface autodoc doctreel 123 17 2 Documentation on exports autodoc_doctree 123 cmd type 1 EE 123 doctree 1 rest ype ctos e p Mae 124 doctree is empty 1 pred o ooooooooomoooo 124 is nonempty doctree 1 pred 124 empty doctree 1 predi ec cece eee ee eee 124 doctree_insert_end 3 pred ooooooooooo 124 doctree_insert_before_section 3 pred 124 doctree concat 3 pred sais EEN e ede 124 Gelenker Ze dere eh SEENEN 125 doclabel 1 F BbyDe a eere aded ete ra Ep 125 doe link apro i erus eoe PEE Re ETUR Ge 125 doclink islocal 1 pred iusso ven om apes 125 doctokens 1 regtype 0 0 eee cere e eens 125 section prop 2 TEEN 125 section_select_prop 3 pred oooooooooooo 125 doctree save 2 Pred xiiroescec meer eR eon a 125 doctree restore 2 pred 02 1 ree 125 doctree simplify 2 pred 5 4 2s eser tke PETERE 125 doctree putvars 5 red 125 doctree scan and save refs 2 pred 126 doctree prepare docst translate and write 3 pred 12
116. eee 119 docst message 2 eek binge bes bebe 118 docst message i 0 eee eee 118 docst modname 2 eee 118 d cst modtype 2 zT REM 121 docst muar get 3 sese 119 docst muar Lookup eee ee eee 119 docst mvar replace ii esses 119 docst new no SrC A4 enn 117 docst new eub seen 118 docst new with src 6 eese 118 docst no components 1 se esses 118 do st opt 2 nein E EENS d ee 118 docst opts 2 EEN iR A I amet 117 docst set currmod 3 eese 117 d cst set Bi a id ER RA 117 te E te EE 129 doctree c ncat 3 socxiilsu ied tei dps ks 124 doctree insert before section 3 124 doctree insert end 3 sees 124 doctree is emptu l cee eee eee ee 124 doctree_prepare_docst_translate_and_write 3 chat del EP 126 doctree ose nea cw pepe btt 125 doctree restore 2 een 125 doctree save 2 eee ren 125 doctree scan and save refs 2 126 doctree sinplify 2 oii et 125 doctree to rawtext 3 eee eee 126 doctree translate and write 3 126 Ke RE 133 168 E empty doctree 1 dete gui 124 ensure cache dir 1 eee 148 ensure output dir 1 i nora eeng a ees 148 ensure output dir prepared 2 112 So o lbi gg edu visus 155 escape String i eese 126 F false f i socilmt LEN NITORE X ER BEES 49 file format name 2 eee 148 file forma
117. egates system file utils make system extra distutils dirutils lists terms make make rt pillow html Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 23 2 Documentation on exports autodoc html template img url 2 PREDICATE Usage img url Name Url Description Obtain the URL where image Name is or will be found Call and exit should be compatible with Name is an atom atm 1 Url is a string a list of character codes string 1 fmt html template 3 PREDICATE No further documentation available for this predicate 144 The Ipdoc Documentation Generator Chapter 24 Man Pages man Backend 145 24 Man Pages man Backend Author s Jose F Morales Manuel Hermenegildo 24 1 Usage and interface autodoc man D e Library usage use_module library autodoc_man e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc doctree lpdocsrc src autodoc images lpdocsrc src autodoc aux lpdocsrc src comments fastformat System library modules lists Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system in
118. elsel dicta 77 80 a eh gr Im MARGARET 95 98 N n assrt body bi u uo ERE eund 54 55 nabody 15 E 51 54 The Ipdoc Documentation Generator 61 62 63 64 65 66 74 78 79 80 82 native 1 85 86 native 2 ossis 61 74 77 78 79 80 81 native EE 3 77 nativeprops pl E 103 NetsCaper EE 8 new item in description list 27 EE e EE 69 nlist 2 o abvvDUnS ID M ues 61 68 MNS PING Ayo sate Gis LR A EE EHI 61 62 EE its 103 104 no choicepoints l cee eee eee 77 80 NO exCeption EE aks 77 81 no exc ption 2 Ee E Mee 77 81 no rtcheck 1 iio o e ae Se oa ees 61 74 no signal WEE 77 81 NOSSipnal 2i de Gee E Senn 77 81 non EE 77 81 D TEE 77 81 nonvar l 62 63 64 65 66 67 70 97 98 normalize index cmd 2 s 151 152 notcovered 4d EEN 77 81 not A iu eina a a a N d aT 105 not_fails 1 77 81 97 98 99 100 101 not further inst 1 eee 54 not further inst 2 61 73 97 98 not mut exclusive 1 ce eee eee 77 82 nu m 1 i ie ubl Reb ees bee eee 61 63 64 102 num c ode 4 Lic AS cele te Mek 61 71 num solutions 2 eee 77 82 O OB 235 ore eer AA d Ron 101 one sided printing ee cece eae 16 EEN do i derat 19 operator Specifier sss 61 67 Operators voce Pere Pee E t 123 option comment 2 s s 16 115 116 P DE due n s re I M E ENS S pela 95 97 EEN 95 100 p bsnini ede eb
119. eneral improvements and bug fixes Designed a logo for LPdoc Jose Morales LPdoc comments can now be written using style comment syntax Manuel Hermenegildo Now commas etc are allowed in section names so that they can be used in other formats They are eliminated automatically in texi and info This avoids wrong section names and thus dangling pointers in generated texinfo files Manuel Hermenegildo Eliminated superfluous copy of summary in info mode Manuel Hermenegildo Eliminated unsupported chars that broke texi manual cross referencing Manuel Hermenegildo Improved treatment of accents dotless i and dotless j o etc Manuel Hermenegildo Initial size passed to xdvi more appropriate for current xdvis Manuel Hermenegildo Accents in bibliography fixed Manuel Hermenegildo Now repeated sections are disambiguated Manuel Hermenegildo Eliminated unnecessary escaping especially for amp Manuel Hermenegildo Better detection of when version is not available Manuel Hermenegildo Added new doc address _ comment which is the right place to put address contact information in manuals Jose Morales The Ipdoc Documentation Generator Added new version command expands to the version of the software to be documented Jose Morales Shorter SETTINGS p1 files with some rudimentary assertion based check ing of options Jose Morales Bug fix include and includeverbatim a
120. ength 2 predicate if it is called as in the first mode of usage above note that the previous pred assertion already conveys such information however it also compelled the predicate calls while the success assertion does not success length L N list var gt list integer Usage success AssertionBody The following properties should hold at call time AssertionBody is a predicate assertion body s_assrt_body 1 success 2 DECLARATION success assertion This assertion is similar to a success 1 assertion but it is explicitely qualified with an assertion status The status of non qualified success 1 assertions is assumed to be check Usage AssertionStatus success AssertionBody The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is a predicate assertion body s assrt body 1 test 1 DECLARATION This assertion is similar to a success assertion but it specifies a concrete test case to be run in order verify partially that the predicate is working as expected For example the following test will verify that the length predicate works well for the particular list given test length L N L 1 2 552 gt N 4 Usage test AssertionBody The following properties should hold at call time AssertionBody is a predicate assertion body s_assrt_body 1 Chapter 4 The Ciao assertion package 45 test
121. ents have choicepoints goal Usage have choicepoints X Description A call to X creates choicepoints indep 1 PROPERTY Usage indep X Description The variables in pairs in X are pairwise independent The following properties hold globally This predicate is understood natively by CiaoPP as indep X native 2 indep 2 PROPERTY Usage indep X Y Description X and Y do not have variables in common The following properties hold globally This predicate is understood natively by CiaoPP as indep X Y native 2 80 The Ipdoc Documentation Generator is det 1 PROPERTY is det X All calls of the form X are deterministic i e produce at most one solution or do not terminate In other words if X succeeds it can only succeed once It can still leave choice points after its execution but when backtracking into these it can only fail or go into an infinite loop Meta predicate with arguments is det goal Usage is det X Description All calls of the form X are deterministic linear 1 PROPERTY linear X X is bound to a term which is linear i e if it contains any variables such variables appear only once in the term For example 1 2 3 and A B are linear terms while f A A is not Usage linear X Description X is instantiated to a linear term The following properties hold globally This predicate is understood natively by CiaoPP native 1 mshare 1 P
122. eprops pl and basic props pl In this way space is saved but sacrifying performance due to usage of meta calls and external methods in the libraries Default e yes Expand library predicates inline as far as possible In this way the code is faster because its avoids metacalls and usage of external methods but the final executable could be bigger e rtchecks asrloc Controls the usage of locators for the assertions in the error messages The locator says the file and lines that contains the assertion that had failed Valid values are e no Disabled e yes Enabled Default e rtchecks predloc Controls the usage of locators for the predicate that caused the run time check error The locator says the first clause of the predicate that the violated assertion refers to e no Disabled 104 The Ipdoc Documentation Generator e yes Enabled Default e rtchecks callloc e no Do not show the stack of predicates that caused the failure e predicate Show the stack of predicates that caused the failure Instrument it in the predicate Default e literal Show the stack of predicates that caused the failure Instrument it in the literal This mode provides more information because reports also the literal in the body of the predicate e rtchecks namefmt e long Show the name of predicates properties and the values of the variables e short Only show the name of the predicate in a reduced format Default 12 1 Usage and interface
123. equesting it see the documentation for the doc 2 declaration Judicious use of these assertions allows at the same time docu menting the program code documenting the external use of the module and greatly improving the debugging process The latter is possible because the assertions provide the compiler with information on the intended meaning or behaviour of the program i e the specification which can be checked at compile time by a suitable preprocessor static analyzer and or at run time via checks inserted by a preprocessor Machine readable comments are also declarations included in the source program but which contain additional information intended to be read by humans i e this is an instantiation of the literate programming style of Knuth Knu84 Typical comments include title author s bugs changelog etc Judicious use of these comments allows enhancing at the same time the documentation of the program text and the manuals generated from it lpdoc requires these assertions and comments to be written using the Ciao system assertion language A simple compatibility library is available in order to make it possible to compile programs documented using assertions and comments in traditional constraint logic program ming systems which lack native support for them see the compatibility directory in the 1pdoc library Using this library such assertions and comments are simply ignored by the compiler This compatibility library
124. er index to be placed in an installation directory and which provide pointers to the docu ments generated see below If the main file is an application and the man option is selected then 1pdoc looks for a usage message 1 fact which should contain a string as argument and will use that string to document the usage of the application i e it will be used to fill in the synopsis section of the man page output name determines the base file name of the main documents generated by Ipdoc By default it is equal to the main file name or if the main file name ends with doc then it is equal to the name without the doc suffix This is useful when the name of the documentation file to be produced needs to have a name that is not directly related to the main file being documented index determines the list of indices to be included at the end of the document These can include indices for defined predicates modules concepts etc For a complete list of the types of indices available see index comment 2 in autodoc or type lpdoc help for a listing A setting of all generates all the supported indices but beware of limitations in the number of simultaneous indices supported in many texinfo installations bibfile determines a list of bib files one file per path ie files containing bibliographic entries in bibtex format This is only relevant if you are using cita tions in the text using the cite command In that case those will be
125. er st 2 prop horari liada ERE A 73 side 2 POD ere trireme ei es aie tae ae es 74 regtype 1 DEI cds ceu wes riu ze ge Red Aun Ee ZE 74 e A O letti Ure TURA 74 native 2 Prop ia A 74 NOt Checks Prop Lic 74 o EE 75 A E a Up bte wae ow tl t berg 75 bind ams tl erer ageet te xe ER c octo ds 75 grror Areg T EE bevor he err eer Re Rd 75 o O A ation 75 Y A AN 75 Dag vales L regtype oorr etre 75 pe type 1 prop a eet ne Ed 76 iv The Ipdoc Documentation Generator 8 Properties which are native to analyzers 77 8 1 Usage and interface native propsl eee e eee 77 8 2 Documentation on exports native_props 77 clique TEE ee Edge eerie Ea UIN e TT elique l AL Prop ereis EE 78 c nstraint 1 Stop o gesn aia 78 Goyered l E EE 78 covered 2 prop WEE 78 exception prop AE tes 78 E EE 78 Lus LUODIOB asia neto repos dede dace d eee TO edd 79 finite solutions 1 prop ege xg ER deen 79 Have choicepoints 1 pFfOD cLoeer each then es 79 Indep IPOD EE 79 Indep 2 EG 79 det TL EE 79 linear MS A oie we n n ea b oat 80 mshare prop ewe eege qr RR E HERR 80 mut exclusive 1 prop ss mcn e E ER CO EECEY WE De 80 no choicepoints 1 prop 80 no_exception 1 Lee cs win decd ee eR RETO Peet E 81 no exception 2 prop ur oi andere ev ees 81 Ee We ees bier woe AE Ma 81 j signal 2 Ehe y elg qe E d eres 81 non det Prop iD 81 nonground 1 proprio arce 81 not covered Pl prop 2
126. ertion lesse 48 comments machine readable nnnnaaaaanaaa 41 comp assertion na 45 compatibility properties ooooooooocooooo 57 component Des 4 CONTENUS ALES EE AE Pee d ane ea 18 COByElglit 2 2 35b RUNE MR REIR 34 date c a xat Id dete pv el EOD ERN 29 decl assertion msd ia eI Den o vates 47 description listoi nir ema EE armed Oe Meder 26 document structure 16 documentation format 111 documentation sting 32 The Ipdoc Documentation Generator E emacs Ciao mode 36 Emacs accessing info files 19 Emacs generating manuals from 15 Emacs LPdoc mode 15 email Address e eum IRE REPRE 29 email addresses 29 emphlasis face iesus pev eec RS RETE ERR RR 27 encapsulated postscript eee eee 30 entry ASSIM esee De eet ge m Re 46 enumerated Det 26 ESCAPE SEQUENCES s aser nee eee ed ah 26 example of Ipdoc use 89 exit assertion cc ovv EEG UENIRE 46 F false assertion i22 mee Ege qur 49 fixed format test 27 fixed width font 27 TOOT bere oe Sis ote DES e LSU eal ed 27 formatting commands 25 41 framed Dee e sett ee be te ierit 27 G generating from Emacs 0oooooooocccccccccoo 15 generating manuals eec eseri ereid e inadae nnig 15 H hard side effectS o oooooooooomomomomooo 83 html index page 18 I image Tle EE 30 images inserting poe erra KAE eee 30 images scaling scos
127. es autodoc html 139 autodoc escape string hook 5 pred 139 autodoc rw command hook 4 pred 139 autodoc finish hook 1 pred vanos s xe DR nes 139 autodoc gen alternative hook 2 pred 140 Resource Handling for the HTML Backend 141 22 1 Usage and interface autodoc html resources 141 22 2 Documentation on exports autodoc html resources 141 prepare web skel 1 red 141 prepare mathjax pred ii ces oko RR Ehe 141 using mathjax 1 pred c 6e2 ees eee e ees Ptr ee od 141 Template Support for the HTML Backend 143 23 1 Usage and interface autodoc html template 143 23 2 Documentation on exports autodoc html template 143 img url 2 pred o ceases et E Gier 143 fmt html template 3 pred ooooooooooo 143 Man Pages man Backend 145 24 1 Usage and interface autodoc man 145 24 2 Documentation on multifiles autodoc man 145 autodoc rw command hook 4 pred 145 autodoc finish hook 1 pred o oo oo o 145 autodoc gen alternative hook 2 pred 145 Filesystem Abstraction 147 25 1 Usage and interface autodoc filesystem 147 25 2 Documentation on exports autodoc_filesystem 147 filename 1 rei pelan aos da aa 147 basename 1 regtype 0 cece eee eee eens 147 subtarget l restype s
128. es props regtypes declarations etc This can be shut off with the shorttoc option Made more silent in normal conditions file inclusion is muted now unless v option is selected A single texi file is now constructed by grouping the texic files gen erated for all components in which the references and menus are resolved This has the advantage that the process of resolving references and menus has now been sped up very significantly Also texi is now a valid tar get perhaps useful for distributions The generated files now have texic texinfo component Now declarations are always documented as long as there is a dec1 asser tion Also they are now documented in a separate section e Bug fixes and other minor improvements The directory containing html manual is now called BASENAME html instead of just BASENAME which was confusing Now requesting building a ps only does not leave a dvi behind useful for distributions File names can now include the symbol _ even if they contain figures TeX related intermediate files are now cleaned up after each run in order to avoid clutter Fixed modes which was broken since going to the new normalizer was normalizer problem Fixed problem with no documentation when only modes given Fixed duplication of documentation for internal predicates when also ex ported Minor formatting problem when no documentation nor definition found for a regtype fixed Determining exports
129. es should hold at call time PropertyConjunction is either a term or a conjunction of terms The main functor and arity of each of those terms corresponds to the definition of a property The first argument of each such term is a variable which appears as a head argument property conjunction 1 PREDICATE Usage trust PropertyConjunction Description This assertion also provides information on a clause program point It is identical syntactically to a check 1 assertion However the properties stated are not taken as something to be checked but are instead trusted by the compiler While the compiler may in some cases detect an inconsistency between a trust 1 assertion and the program in all other cases the information given in the assertion will be taken to be true As a result if these assertions are erroneous they can introduce bugs in programs Thus trust 1 assertions should be written with care Chapter 4 The Ciao assertion package 49 An important use of these assertions is in providing information to the compiler which it may not be able to infer from the program either because the information is not present or because the analyzer being used is not precise enough In particular providing information on external predicates which may not be accessible at the time of compiling the module can greatly improve the precision of the analyzer This can be easily done with trust assertion The following properties should hol
130. es should hold at call time AssertionBody is an assertion body assrt_body 1 This assertion is similar to a prop 1 assertion but it is explicitely qualified Non qualified prop 1 assertions are assumed the qualifier check Usage AssertionStatus prop AssertionBody The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is an assertion body assrt_body 1 This assertion provides information about the external calls to a predicate It is identical syntactically to a calls 1 assertion However they describe only external calls i e calls to the exported predicates of a module from outside the module or calls to the predicates in a non modular file from other files or the user These assertions are trusted by the compiler As a result if their descriptions are erroneous they can introduce bugs in programs Thus entry 1 assertions should be written with care An important use of these assertions is in providing information to the compiler which it may not be able to infer from the program The main use is in providing information on the ways in which exported predicates of a module will be called from outside the module This will greatly improve the precision of the analyzer which otherwise has to assume that the arguments that exported predicates receive are any arbitrary term Usage entry AssertionBody The following properties should h
131. escription An internal label doclink at 2 PREDICATE No further documentation available for this predicate doclink is local 1 PREDICATE No further documentation available for this predicate doctokens 1 REGTYPE Usage Description Primitive doctree subset ready for output not further reducible section prop 2 PREDICATE No further documentation available for this predicate section select prop 3 PREDICATE No further documentation available for this predicate doctree_save 2 PREDICATE doctree_restore 2 PREDICATE doctree simplify 2 PREDICATE No further documentation available for this predicate doctree putvars 5 PREDICATE Usage doctree putvars RO DocSt PDict VarDict R Description Traverse RO and replace each var Name doctree item with a fresh vari able B For each replacement the term B Var is introduced in VarDict where Var is the associated value to Name in the dictionary PDict 126 The Ipdoc Documentation Generator The following properties should hold at call time Intermediate tree representation for documentation docstate DocSt The following properties should hold upon exit Intermediate tree representation for documentation doctree scan and save refs 2 Usage doctree scan and save refs R DocSt Description Scan and save the references of the doctree The following properties should hold at call time Intermediate tree representation for documentation docstate D
132. et 4 main output name 2 get subbase 3 absfile to relfile 3 clean a11 0 clean docs no texi 0O clean all temporal 0 clean intermediate 0 clean tex intermediate 0 Regular Types filename 1 basename 1 subtarget 1 e Other modules used Application modules lpdocsrc src autodoc settings lpdocsrc src autodoc structure lpdocsrc src autodoc state lpdocsrc src component versions System library modules aggregates make system_extra terms distutils dirutils system component_ registry component_registry Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 25 2 Documentation on exports autodoc filesystem filename 1 REGTYPE Usage filename X Description X is the name of a file basename 1 REGTYPE Usage basename X Description X is the base name of a file without extension 148 The Ipdoc Documentation Generator subtarget 1 REGTYPE Usage Description The kind of intermediate final results for a single documentation pro cessing unit module file format name 2 PREDICATE No further documentation available for this predicate supported file format 1 PREDICATE No further documentation available for this predicate file format provided by backend 3 PREDICATE Usage fil
133. eval 1 is det 1 gnd 1 Required by the nonfailure test type 2 native 1 REGTYPE sideff 2 66 The Ipdoc Documentation Generator gndstr T If the following properties hold at call time T is currently ground it contains no variables then the following properties hold globally gndstr T is evaluable at compile time All calls of the form gndstr T are deterministic gndstr T The following properties hold upon exit T is a ground compound term Usage gndstr T Description T is a ground compound term The following properties hold globally This predicate is understood natively by CiaoPP constant 1 General properties constant T The following properties hold globally constant T is side effect free constant T If the following properties hold at call time T is currently a term which is not a free variable then the following properties hold globally constant T is evaluable at compile time All calls of the form constant T are deterministic constant T The following properties hold upon exit T is an atomic term an atom or a number Usage constant T Description T is an atomic term an atom or a number callable 1 General properties callable T The following properties hold globally callable T is side effect free callable T If the following properties hold at call time T is currently a term which is not a free varia
134. f predicate length 2 see lists pred length L N list var gt list integer Computes the length of L pred length L N var integer gt list integer Outputs L of length N pred length L N list integer gt list integer Chapter 4 The Ciao assertion package 43 Checks that L is of length N Usage pred AssertionBody The following properties should hold at call time AssertionBody is an assertion body assrt_body 1 pred 2 DECLARATION This assertion is similar to a pred 1 assertion but it is explicitely qualified Non qualified pred 1 assertions are assumed the qualifier check Usage AssertionStatus pred AssertionBody The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is an assertion body assrt_body 1 texec 1 DECLARATION This assertion is similar to a calls 1 assertion but it is used to provide input data and execution commands to the unit test driver Usage texec AssertionBody The following properties should hold at call time AssertionBody is a call assertion body c_assrt_body 1 texec 2 DECLARATION This assertion is similar to a texec 1 assertion but it is explicitely qualified with an assertion status Non qualified texec 1 assertions are assumed to have check status Usage AssertionStatus texec AssertionBody The following properties sho
135. f text in a framed box with round corners end cartouche marks the end of a section of text in a framed box begin falert marks the beginning of a section of text in a framed boz for alert messages end alert marks the end of the alert message sectiont text starts a section whose title is text Due to a limitation of the info format do not use or or in section subsection title chapter etc headings Osubsectionitert starts a subsection whose title is text footnote text places text in a footnote hfill introduces horizontal filling space may be ignored in certain formats bf tert text will be formatted in bold face or any other strong face em tert text will be formatted in italics face or any other emphasis face tt tert text will be formatted in a fixed width font i e typewriter like font Okeyikey key is the identifier of a keyboard key i e a letter such as a or a special key identifier such as RET or DEL and will be formatted as or in a fixed width typewriter like font sp N generates N blank lines of space Forces also a paragraph break p forces a paragraph break in the same way as leaving one or more blank lines Onoindent used at the beginning of paragraph states that the first line of the paragraph should not be indented Useful for example for avoiding indentation on paragraphs that are continuations of other paragraphs such as after a verbatim e Indexi
136. f version maintenance that should be performed by the emacs Ciao mode Example doc version_maintenance dir version Version control info is kept in directory version See the definition of version_ maintenance_type 1 for more information on the different version maintenance modes See the documentation on the emacs Ciao mode in the Ciao manual for information on how to automatically insert version control doc 2 declarations in files The version maintenance mode can also be set alternatively by inserting a comment such as Local Variables 4 mode CIAO update version comments off 4 End The lines above instruct emacs to put the buffer visiting the file in emacs Ciao mode and to turn version maintenance off Setting the version maintenance mode in this way Chapter 3 Documentation Mark up Language and Declarations 37 has the disadvantage that 1pdoc will not be aware of the type of version maintenance being performed the lines above are comments for Prolog However this can be useful in fact for setting the version maintenance mode for packages and other files meant for inclusion in other files since that way the settings will not affect the file in which the package is included The following properties should hold upon exit CommentType version maintenance 2 VersionMaintenanceType a type of version maintenance for a file version maintenance type 1 Usage 19 doc CommentType PredName
137. facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support y 7 2 Documentation on exports basic_props term 1 REGTYPE The most general type includes all possible terms General properties term X ter ter The following properties hold globally term X is side effect free sideff 2 m X The following properties hold globally term X is evaluable at compile time eval 1 m X The following properties hold globally term X is equivalent to true equiv 2 Usage term X 62 The Ipdoc Documentation Generator Description X is any term The following properties hold globally This predicate is understood natively by CiaoPP int 1 native 1 REGTYPE The type of integers The range of integers is 2 2147483616 2 2147483616 Thus for all practical purposes the range of integers can be considered infinite General properties int T The following properties hold globally int T is side effect free int T If the following properties hold at call time T is currently a term which is not a free variable then the following properties hold globally int T is evaluable at compile time All calls of the form int T are deterministic int T The following properties hold upon exit T is an integer The following properties hold globally Indicates the type of test that a predicat
138. file formats 1 load vpaths O viewer 3 xdvi 1 xdvisize 1 pdfview 1 psview 1 htmlview 1 bibtex 1 tex 1 texindex 1 dvips 1 ps2pdf 1 makeinfo 1 makertf 1 rtftohlp 1 convertc 1 make system extra make make rt aggregates distutils distutils Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support V Y 19 2 Documentation on exports autodoc_settings Ipdoc option 1 PREDICATE Defines the global options of lpdoc The predicate is of type data verify settings 0 PREDICATE No further documentation available for this predicate check setting 1 PREDICATE No further documentation available for this predicate setting value or default 2 PREDICATE Usage setting value or default Var Value 132 The Ipdoc Documentation Generator Description Returns in Value the value of the variable Var In case this variable does not exists it returns a default value If there is no default value for the variable Var it fails setting value or default 3 No further documentation available for this predicate setting value 2 No further documentation available for this predicate all setting values 2 No further documentation available for this predicate get command option 1 No further documentation available for this pre
139. fo term compare term typing hiord rt debugger support J 24 2 Documentation on multifiles autodoc_man autodoc_rw_command_hook 4 PREDICATE The predicate is multifile Usage autodoc_rw_command_hook Backend DocSt Command NewCommand The following properties should hold at call time Backend is a supported backend backend_id 1 docstate DocSt docstate 1 Intermediate tree representation for documentation doctree 1 Intermediate tree representation for documentation doctree 1 autodoc finish hook 1 PREDICATE No further documentation available for this predicate The predicate is multifile autodoc gen alternative hook 2 PREDICATE No further documentation available for this predicate The predicate is multifile 146 The Ipdoc Documentation Generator Chapter 25 Filesystem Abstraction 147 25 Filesystem Abstraction Author s Jose F Morales This module provides definitions to assign unique file system paths and names for each of the intermediate and final results of documentation generation 25 1 Usage and interface autodoc filesystem gt e Library usage use_module library autodoc_filesystem e Exports Predicates file_format_name 2 supported file format 1 file format provided by backend 3 clean_fs_db 0 get output dir 2 get cache dir 2 ensure output dir 1 ensure cache dir 1 main absfile in format 2 main absfile for subtarget 3 absfile for aux 3 absfile for subtarg
140. for an assertion assrt type 1 REGTYPE The admissible kinds of assertions assrt type pred assrt type prop assrt type decl assrt type func assrt type calls assrt type success assrt type comp assrt type entry assrt type exit assrt type test assrt type texec assrt type modedef Usage assrt type X Description X is an admissible kind of assertion predfunctor 1 REGTYPE Usage predfunctor X Description X is a type of assertion which defines a predicate propfunctor 1 REGTYPE Usage propfunctor X Description X is a type of assertion which defines a property docstring 1 PROPERTY Usage docstring String Description String is a text comment with admissible documentation commands The usual formatting commands that are applicable in comment strings are defined by stringcommand 1 See the 1pdoc manual for documentation on comments Chapter 6 Declaring regular types 57 6 Declaring regular types Author s Manuel Hermenegildo Pedro L pez Francisco Bueno This library package adds declarations and new operator definitions which provide simple syntactic sugar to write regular type definitions in source code Regular types are just properties which have the additional characteristic of being regular types basic_props regtype 1 defined below For example this library package allows writing regtype tree X X is a tree instead of the more cumbersome p
141. he assertion hold The usual formatting com mands that are applicable in comment strings can be used see stringcommand 1 See the 1pdoc manual for documentation on assertion comments Usage assrt body X Description X is an assertion body head pattern 1 PROPERTY A head pattern can be a predicate name functor arity predname 1 or a term Thus both p 3 and p A B C are valid head patterns In the case in which the head pattern is a term each argument of such a term can be e A variable This is useful in order to be able to refer to the correspond ing argument positions by name within properties and in comments Thus p Input Parameter utput is a valid head pattern LC e A variable as above but preceded by a mode This mode determines in a compact way certain call or answer properties For example the head pattern p Input Parameter Output is valid as long as 1 is declared as a mode Acceptable modes are documented in library basicmodes and library isomodes User defined modes are documented in modedef 1 e Any term In this case this term determines the instantiation state of the correspond ing argument position of the predicate calls to which the assertion applies H e A ground term preceded by a mode The ground term determines a property of the corresponding argument The mode determines if it applies to the calls and or the successes The actual property referred to is that given by th
142. he format of the different parts of the assertion body are given by n assrt body 5 and its auxiliary types Usage c_assrt_body X Description X is a call assertion body Chapter 5 Types and properties related to assertions 55 s assrt body 1 REGTYPE This predicate defines the different types of syntax admissible in the bodies of pred 1 func 1 etc assertions The following are admissible Pr CP gt AP CO Pr CP gt AP Pr gt AP CO Pr gt AP where e Pr is a head pattern head_pattern 1 which describes the predicate or property and possibly gives some implicit call answer information e CP is a possibly empty complex argument property complex arg property 1 which applies to the calls to the predicate e AP is a possibly empty complex argument property complex arg property 1 which applies to the answers to the predicate if the predicate succeeds These only apply if the possibly empty properties given for calls in the assertion hold e CO is a comment string docstring 1 This comment only applies if the possibly empty properties given for calls in the assertion hold The usual formatting com mands that are applicable in comment strings can be used see stringcommand 1 The format of the different parts of the assertion body are given by n assrt body 5 and its auxiliary types Usage s_assrt_body X Description X is a predicate assertion body g assrt body 1 REGTYPE This predic
143. hich printed manuals and several other printing and on line formats can be easily generated automatically including info html etc There is also some limited support for direct output in unix man format and direct html but note that html can also be generated in a better way by first generating texinfo and then using one of the available converters For texinfo the documentation for a module is a texinfo chapter suitable for inclusion in a wrapper main document file A simple example of the use of this library for generating a texinfo reference manual including a driver script useful Makefiles etc is included with the library source code Other examples can be found in the Ciao documentation directory i e the Ciao manuals themselves A simple example of the use of this library for generating a texinfo reference manual in cluding a driver script useful Makefiles etc is included with the library source code Other examples can be found in the Ciao documentation directory i e the Ciao manuals themselves 112 The Ipdoc Documentation Generator 15 1 Usage and interface autodoc a E e Library usage use module library autodoc e Exports Predicates index comment 2 reset_output_dir_db 0 ensure_output_dir_prepared 2 get_autodoc_opts 3 autodoc_gen_doctree 5 fmt_infodir_entry 3 autodoc_ compute_grefs 3 autodoc_translate_doctree 3 autodoc_finish 1 autodoc_ gen_alternative 2 Multifiles autodo
144. i ainiai pue mi EN xus 30 including a predicate definition snasssnaa 30 including an Image 30 including code RPSL QU ERE da 30 incl ding 11168354 uda cU TE dee e ROLE AR 30 including images eiser e244 e er DEG Dee ead 30 including or not authors 00 16 including or not bug info 16 including or not changelog 16 including or not versions patches 16 indentation avoiding 0 27 index pages out of order 18 Concept Index info path lisboa eR END ERE 20 installation 2 5 E eu RISUS 3 installation of manualS o ooooooooooo 18 instantiation Droperties esses eese 57 internals manual 22 IMC ii a a 34 NS A ius eeni e E AE ede 27 item in an itemized lisSt o o 26 itemized let edle MEN ENN ee ee 26 K keyboard key 27 L LaTeX notation 0 ec cee eee eee eee 29 letter size paper EE m rp abe ee ee 17 library 55 a e Qe Ee d 3 literate programming ssssse eene 19 log OF Changes ve cad vea dv Der suu mee eue 36 M machine readable comments 32 main body v eee a Neu dE UPC PY 34 maim file sedo eripe e LP UMS 4 Makefile vicio di OBEN 107 module comment 34 module declaration lesen 111 N new item in description list 27 O one sided printing eee 16 E page numbering changing 16 page size cha
145. i files can also be generated with the GNU Texinfo package which provides among others the texi2dvi command However Texinfo itself requires the standard tex document processing package In order to use texi2dvi instead of tex when processing documents you should change the variable TEX in the Makefile skel file in the 1ib direc tory before installing 1pdoc Generating the dvi file requires that the texinfo tex file containing the relevant macros be available to tex This file is normally included with modern tex distributions although it may be obsolete An appropriate and up to date one for 1pdoc is provided with the 1pdoc distribution stored in the 1pdoc library during instal lation and used automatically when 1pdoc runs tex The texindex package is required in order to process the indices If you use references in your manual then the bibtex package is also needed texindex and bibtex are included with most tex distributions Generating ps files ps files are generated from the dvi files using the dvips command this again can be changed in the Makefile skel file in the lib directory This command is included with standard tex distributions Generating pdf files pdf files are currently generated from the texi file using the pdftex command this again can be changed in the Makefile skel file in the lib direc tory This command is included in current Linux distributions Generating html files html files are generated dire
146. ication Several of these declarations can appear per module When generating documentation automatically the text in the Text fields will be used as items in an itemized list of module or application bugs Example doc bug Comment text still has to be written by user The following properties should hold upon exit CommentType bug 2 CommentText is a documentation string docstring 1 Usage 17 doc Version CommentText Description Provides a means for keeping a log of changes Version contains the version number and date corresponding to the change and CommentText an expla nation of the change Several of these declarations can appear per module When generating documentation automatically the texts in the different CommentText fields typically appear as items in an itemized list of changes The emacs Ciao mode helps tracking version numbers by prompting for version comments when files are saved This mode requires version comments to appear in reverse chronological order i e the topmost comment should be the most recent one Example doc version 1 1 21 1998 04 18 15 05 01 EST Added some missing comments Manuel Hermenegildo The following properties should hold upon exit Version is a complete version descriptor version_descriptor 1 CommentText is a documentation string docstring 1 Usage 18 doc CommentType VersionMaintenanceType Description Defines the type o
147. iccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 31 2 Documentation on exports autodoc images locate and convert image 4 PREDICATE Usage locate and convert image SrcSpecS AcceptedFormats DocSt TargetFiles Description The image at SrcSpecS is located as one of the known formats known_ format 1 and converted to one of the AcceptedFormats The target file is called TargetFiles Call and exit should be compatible with SrcSpecS is a string a list of character codes string 1 AcceptedFormats is a list of atoms list 2 docstate DocSt docstate 1 TargetFileS is a string a list of character codes string 1 clean_image_cache 0 PREDICATE Usage Description Clean the cache for image copy conversions 162 The Ipdoc Documentation Generator References 163 References Bue95 Bue98 DEDC96 DL93 DLGH97 DLGHL97 Her99 Her00 JL88 JM94 Knu84 LGHD96 MH89 F Bueno The CIAO Multiparadigm Compiler A User s Manual Technical Report CLIP8 95 0 Facultad de Inform tica UPM June 1995 F Bueno Using Assertions for Static Debugging of CLP A Manual Technical Report CLIP1 98 0 DISCIPL Project CLIP Group UPM June 1998 P Deransart A Ed Dbali and L Cervoni Prolog The Standard Springer Verlag 1996 S K Debray and N
148. ich is also accessible via WWW After setting docdir to this directory in the SETTINGS p1 file and selecting infoindex and htmlindex for the docformats variable lpdoc install lpdoc uninstall will install uninstall all manuals in all the selected formats in this directory and create and maintain the corresponding html and info indices Then setting the environment variables as follows e g for csh in cshrc setenv DOCDIR home clip public_html lpdoc_docs setenv INFOPATH usr local info DOCDIR setenv MANPATH DOCDIR MANPATH Example files for inclusion in user s or common shell initialization files are included in the lpdoc library More complex setups can be accommodated as for example installing different types of manuals in different directories However this currently requires changing the docformats and docdir variables and performing lpdoc install for each installation format directory 2 8 Some usage tips This section contains additional suggestions on the use of 1pdoc 2 8 1 Ensuring Compatibility with All Supported Target Formats One of the nice things about lpdoc is that it allows generating manuals in several formats which are quite different in nature Because these formats each have widely different require ments it is sometimes a little tricky to get things to work successfully for all formats The following recommendations are intended to help in achieving useful manuals in all formats e The best result
149. ield of an assertion Le the following is a valid assertion pred foo X Y nonvar var gt ground X ground Y Usage complex arg property Props Description Props is a possibly empty complex argument property property conjunction 1 REGTYPE This type defines the first unabridged format in which properties can be expressed in the bodies of assertions It is essentially a conjunction of properties which refer to variables The following is an example of a complex property in this format e integer X list Y integer X has the property integer 1 and Y has the prop erty list 2 with second argument integer Usage property conjunction Props Description Props is either a term or a conjunction of terms The main functor and arity of each of those terms corresponds to the definition of a property The first argument of each such term is a variable which appears as a head argument property starterm 1 REGTYPE This type defines a second compact format in which properties can be expressed in the bodies of assertions A property starterm 1 is a term whose main functor is 2 and when it appears in an assertion the number of terms joined by 2 is exactly the arity of the predicate it refers to A similar series of properties as in property conjunction 1 appears but the arity of each property is one less the argument position to which they refer first argument is left out and determined by the position of the p
150. ile at each point in which a major part starts The doc title declaration of this file will be used as the part title and the doc module declaration text will be used as the introduction to the part 2 8 6 Documenting reexported predicates Reexported predicates i e predicates which are exported by a module m1 but defined in another module m2 which is used by m1 are normally not documented in the original module but instead a simple reference is included to the module in which it is defined This can be changed so that the documentation is included in the original module by using a doc 2 declaration with doinclude in the first argument see the comments library This is often useful when documenting a library made of several components For a simple user s manual it is often sufficient to include in the 1pdoc SETTINGS p1 file the principal module which is the one which users will do a use module 1 of in the manual This module typically exports or reexports all the predicates which define the library s user interface Note however that currently due to limitations in the implementation only the comments inside assertions but not those in doc 2 declarations are included for reexported predicates 2 8 7 Separating the documentation from the source file Sometimes one would not like to include long introductory comments in the module itself but would rather have them in a different file This can be done quite simpl
151. iles This option can be used in software distributions in which the manuals in the different formats will be generated during installation This is generally more compact but requires the presence of several tools such as tex Emacs etc see Section 14 2 Other software packages required lpdoc page 107 in order to generate the manuals in the target formats during installation 18 The Ipdoc Documentation Generator e lpdoc realclean performs a complete cleanup deleting also the texic files i e it typically leaves only the SETTINGS p1 file This is is the most compact but requires the presence of the tools mentioned above the source files from which the manuals are generated and lpdoc in order to re generate the manuals in the target formats during installation 2 5 Installing a generated manual in a public area Note This part is obsolete It must be updated to describe Ipdoc version 2 0 EMM Once the manual has been generated in the desired formats the Makefile provided also al lows automatic installation in a different area specified by the docdir option in the SETTINGS pl file This is done by typing lpdoc install As mentioned above lpdoc can generate directly brief descriptions in html or Emacs info formats suitable for inclusion in an on line index of applications In particular if the htmlindex and or infoindex options are selected 1pdoc install will create the installation directory place the documentat
152. ilesystem lpdocsrc src autodoc bibrefs autodoc structure System library modules aggregates lists Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 27 2 Documentation on exports autodoc_refsdb compute refs and biblio 1 PREDICATE No further documentation available for this predicate prepare current refs 1 PREDICATE Usage Description Prepare references for the translation of the current file Call and exit should be compatible with docstate Arg1 docstate 1 clean_current_refs 1 PREDICATE Usage 154 The Ipdoc Documentation Generator Description Clean the data stored by prepare current refs 1 Call and exit should be compatible with docstate Arg1 docstate 1 secttree 1 REGTYPE Usage Description A tree of sections secttree_resolve 3 PREDICATE Usage secttree_resolve LabelName Tree Link Description Locate in the section tree Tree the section with label name LabelName and return the Link to the section Call and exit should be compatible with LabelName is a string a list of character codes string 1 Intermediate tree representation for documentation doctree 1 A link to a document label doclink 1 Chapter 28 Error Messages 155 28 Err
153. ined Do not signal undefined properties in text option comment no propsepln Do not put each property in a separate line option comment no biblio Do not include a bibliographical References appe option comment no sysmods Do not include system modules in list of libraries used option comment no engmods Do not include system engine modules in list of libraries used option comment no isoline Do not include textual description that a given usage conforms to the ISO standard option comment propmods Include module name to which props belong option Comment no propuses Do not Include property uses from assertions i option comment shorttoc Produce shorter table of contents no entries for individual defs of preds props etc option comment regtype props Include in the doc for regtypes the global prop stating that they are indeed regtypes option comment onesided For printing on one side default is two option comment no math Disable mathematical environments The following properties should hold upon exit Option is a supported documentation option supported option 1 Text is a string a list of character codes string 1 backend id 1 REGTYPE Usage backend id Id Description Id is a supported backend backend ignores components 1 PREDICATE Usage backend ignores components Id Description Id does not take into account components only documents the mainfil
154. ing documentation automatically the text in ComnentText will be used in one of the last sections or appendices of the corresponding chapter or manual There should be at most one of these declarations per module CommentText may use subsections if substructure is needed Chapter 3 Documentation Mark up Language and Declarations 35 Example doc appendix Other module functionality The following properties should hold upon exit CommentType appendix 2 CommentText is a documentation string docstring 1 Usage 12 doc CommentType ComnentText Description Provides a description of how the library should be loaded Normally this information is gathered automatically when generating documentation automat ically This declaration is meant for use when the module needs to be treated in some special way There should be at most one of these declarations per module Example doc usage Do not use still in development The following properties should hold upon exit CommentType usage 2 CommentText is a documentation string docstring 1 Usage 13 doc CommentType Section Description Insert a program section with name Section Sectioning commands allow a structured separation of the program into parts The division is only for doc umentation purposes so visibility and scope of definitions is not affected by sectioning commands Example doc section Main Steps of the A
155. ing properties should hold upon exit Argi is ground gnd 1 Arg2 is currently ground it contains no variables ground 1 The following properties should hold globally Arg3 is not further instantiated not further inst 2 i length A is a lower bound on the cost of any call of the form p Arg1 Arg2 Arg3 Arg4 A steps_1b 2 u 3 PREDICATE Usage 1 The following properties should hold at call time Arel is currently a term which is not a free variable nonvar 1 Arg2 is a free variable var 1 The following properties should hold upon exit Arg3 is ground gnd 1 98 The Ipdoc Documentation Generator long 1 PROPERTY This is a property describing a list that is longish The definition is long L length L N N gt 100 Usage long L Description L is rather long w 1 PREDICATE Usage Calls should and exit will be compatible with Argl is a list of mytypes list 2 The following properties should hold at call time Argi is currently a term which is not a free variable nonvar 1 mytype 1 PREDICATE No further documentation available for this predicate t 5 PREDICATE Usage t 4 B C D E Description This predicate uses modes extensively Call and exit should be compatible with A is a list list 1 B is a list list 1 C is an integer int 1 D is an integer int 1 E is a list list 1 The following properties should hold at call time A is currently a term
156. ion in the desired formats in this directory and produce and place in the same directory suitable index html and or dir files These files will contain some basic info on the manual extracted from the summary and title respectively and include pointers to the relevant documents which have been installed The infodirheadfile infodirtailfile default examples used in the CLIP group at UPM are included with the distribution should point to files which will be used as head and tail templates when generating the dir files Several manuals coming from different doc directories can be installed in the same docdir directory In this case the descriptions of and pointers to the different manuals will be automatically combined appearing in alphabetic order in the index html and or dir indices and a contents area will appear at the beginning of the html index page Important Note In order for the different components to appear in the correct positions in the index pages mentioned above the traditional C Lexical order must be active In recent Un x systems e g in most current Linux systems this may not be the case There are several possible fixes e For csh put setenv LC COLLATE C in your cshrc e For bash put export LC COLLATE C in your profile e In many systems this can be done globally by the super user E g in many Linux systems set LANG C in etc sysconfig i18n Note that depending on the structure of the manuals being gene
157. is se 0k vlr eu Ne oak 147 file format name 2 De te coders ee doe SER 148 supported file format 1 red 148 file format provided by backend 3 pred 148 clean fs db 0 pred iua cut de eer e ncn 148 get_output dir 2 pred oci cer Speer eg ic 148 get cache dir 2 pred iii 148 ensure output dir 1 pre 148 ensure cache dir 1 red 148 main absfile in format 2 pred ssususrusnusa 148 main absfile for subtarget 3 pred 149 bsfile Tor ux 3 EE 149 absfile for subtarget 4 pred suseusresrsrusa 149 main output name 2 pr d c vic oe bees 149 get_subbase 3 pred EE 149 absfile to relfile 3 red 149 lean ll 0 pred uae Sebald be iS be cien 149 clean docs no texi 0 pred 0ooooooooooo 149 clean all temporal 0 red 149 clean intermediate 0 pred ooooooooomoo 150 clean tex intermediate 0 red 150 ix The Ipdoc Documentation Generator x 26 Indexing Commands Definition and Formatting Re e ee re DA ee ip AAA inc trip A 151 26 1 Usage and interface autodoc Andezl 151 26 2 Documentation on exports autodoc index 151 get idxsub 2 pred 3 ccs Liter RR ye 3 151 get idxbase 3 predice 151 typeindex 5 pred cedat rcc DRE KO 151 idx set Tidices 3 pred esos meii re Ee EET 152 isindex cmd 1 pred uico EE 152 codetype 1 EEN 152 normalize index cmd 3 pred o oo o 152 tad pred NEE 152 fmtindex 3 X
158. is part of the assertions library It defines the basic code related assertions i e those intended to be used mainly by compilation related tools such as the static analyzer or the run time test generator Giving specifications for predicates and other program elements is the main functionality documented here The exact syntax of comments is described in the autodocumenter 1pdoc Knu84 Her99 manual although some support for adding machine readable comments in as sertions is also mentioned here There are two kinds of assertions predicate assertions and program point assertions All predicate assertions are currently placed as directives in the source code i e preceded by Program point assertions are placed as goals in clause bodies 4 1 More info The facilities provided by the library are documented in the description of its component modules This documentation is intended to provide information only at a reference man ual level For a more tutorial introduction to the subject and some more examples please see PBH00 The assertion language implemented in this library is modeled after this design document although due to implementation issues it may differ in some details The purpose of this manual is to document precisely what the implementation of the library supports at any given point in time 4 2 Some attention points e Formatting commands within text strings many of the predicates defined in these mod u
159. istic is det 1 num T The following properties hold upon exit T is a number num 1 The following properties hold globally Indicates the type of test that a predicate performs Required by the nonfailure analyisis test type 2 Usage num T Description T is a number The following properties hold globally This predicate is understood natively by CiaoPP native 1 atm 1 REGTYPE The type of atoms or non numeric constants The size of atoms is unbound General properties atm T The following properties hold globally atm T is side effect free sideff 2 atm T If the following properties hold at call time T is currently a term which is not a free variable nonvar 1 then the following properties hold globally atm T is evaluable at compile time eval 1 All calls of the form atm T are deterministic is_det 1 atm T The following properties hold upon exit T is an atom atm 1 The following properties hold globally Indicates the type of test that a predicate performs Required by the nonfailure analyisis test_type 2 Usage atm T Description T is an atom The following properties hold globally This predicate is understood natively by CiaoPP native 1 struct 1 REGTYPE The type of compound terms or terms with non zeroary functors By now there is a limit of 255 arguments General properties struct T Chapter 7 Basic data types and properties
160. ities of 1pdoc The module headers produce documentation on the module interface Exported predicates properties and types are documented by default module example module bar 1 baz 1 aorb 1 tree of 2 list or aorb 2 q9 2 r 1 p 1 p 5 u 3 l long 1 w 1 mytype 1 t 5 s 1 q 1l assertions basicmodes fsyntax regtypes hiord nativeprops We import two types list 1 and list 2 now in basic props which is hh exported by default from assertions We reexport list 1 reexport library engine basic props list 1 1 use module library lists length 2 4 use module bar ensure loaded foo doc declarations provide additional information doc title Auto Documenter Output for the Example Module doc author Anonymous Author 1 doc author Anonymous Author 2 doc summary This is a brief summary description of the module or file In this case the file is a library doc module This is where general comments on the file go In this case the file is a library which contains some assertion examples for testing the Cemfautomatic documentation system An example of a comment documenting a bug doc bug Library is hard to execute no actual code Standard declarations are documented with the corresponding predicate data r 1 dynamic g 2 multifile p 3 dynamic p 3 meta predicate p 7 90 The Ipdoc Documentation Generator
161. l data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 16 2 Documentation on exports autodoc state supported option 1 PROPERTY Usage supported option Option 116 The Ipdoc Documentation Generator Description Option is a supported documentation option option comment 2 PREDICATE Usage option comment Option Text Description Option is a documentation option which is supported Text describes the effect of selecting that option Currently supported options are option comment verbose Verbose output good for debugging option_comment no_bugs Do not include information on bugs gt option_comment no_authors Do not include author names option_comment no_stability Do not include stability comment n option comment no version Do not include version information gt option_comment no_versioned_output Do not include version in the output nan option comment no changelog Do not include change log s option comment no patches Do not include comments for patches option comment modes Do not translate modes and their arguments except for properties option_comment head_props Do not move head properties to body gt option comment literal props Do not use text to document properties n option comment no propnames Do not include property names in prop text option comment no undef
162. l engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support P 30 2 Documentation on exports autodoc aux read file 2 PREDICATE No further documentation available for this predicate ascii blank lines 2 PREDICATE No further documentation available for this predicate sh exec 2 PREDICATE No further documentation available for this predicate 160 The Ipdoc Documentation Generator Chapter 31 Image Handling 161 31 Image Handling Author s Jose F Morales This module defines the handling of image commands It defines predicates to locate and convert images in the different formats required for documentation Note This part needs better documentation JFMC 31 1 Usage and interface autodoc_images gt e Library usage use_module library autodoc_images e Exports Predicates locate_and_convert_image 4 clean image cache 0O e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc filesystem lpdocsrc src autodoc settings lpdocsrc src autodoc aux System library modules terms make make rt make system extra system errhandle messages format nternal engine modules term basic arithmetic atomic basic attributes basic props bas
163. l be included in the usage in dex In on line manuals a direct access to the corresponding predicate definition may also be generated opt operatorname operatorname which should be in functor arity form is the name of an operator and will be printed in fixed width typewriter like font This command should be used when referring to an operator in a documenta tion string A reference will be included in the usage index In on line manuals a direct access to the corresponding operator definition may also be generated decl deciname declname which should be in functor arity form is the name of a dec laration and will be printed in fixed width typewriter like font This command should be used when referring to a declaration in a documen tation string A reference will be included in the usage index In on line manuals a direct access to the corresponding declaration definition may also be generated 1ib libname libname is the name of a library and will be printed in fixed width typewriter like font This command should be used when referring to a module or library in a documentation string A reference will be in cluded in the usage index In on line manuals a direct access to the corresponding module definition may also be generated apl aplname aplname is the name of an application and will be printed in fixed width typewriter like font This command should be used when referring to an application in a documentation stri
164. le commands e Formatting commands The following commands are used to format certain words or sentences in a special font build itemized lists introduce sections include examples etc comment tert text will be treated as a comment and will be ignored begin itemize marks the beginning of an itemized list Each item should be in a separate paragraph and preceded by an Citem command item marks the beginning of a new item in an itemized list end itemize marks the end of an itemized list begin enumerate marks the beginning of an enumerated list Each item should be in a separate paragraph and preceded by an Citem command end enumerate marks the end of an enumerated list begin description marks the beginning of a description list i e a list of items and their description this list describing the different allowable commads is in fact a description list Each item should be in a separate paragraph and contained in an item itemtext command Chapter 3 Documentation Mark up Language and Declarations 27 item itemtext marks the beginning of a new item in description list and contains the header for the item end description marks the end of a description list begin verbatim marks the beginning of fired format text such as a program example A fixed width typewriter like font is used end verbatim marks the end of formatted text begin cartouche marks the beginning of a section o
165. le for this predicate 20 3 Documentation on multifiles autodoc texinfo autodoc escape string hook 5 PREDICATE No further documentation available for this predicate The predicate is multifile autodoc rw command hook 4 PREDICATE The predicate is multifile Usage autodoc rw command hook Backend Doc t Command NewCommand 138 The following properties should hold at call time Backend is a supported backend docstate DocSt Intermediate tree representation for documentation Intermediate tree representation for documentation autodoc finish hook 1 No further documentation available for this predicate The predicate is multifile autodoc gen alternative hook 2 No further documentation available for this predicate The predicate is multifile The Ipdoc Documentation Generator backend id 1 docstate 1 doctree 1 doctree 1 PREDICATE PREDICATE Chapter 21 HTML Backend 139 21 HTML Backend Author s Jose F Morales 21 1 Usage and interface autodoc html Va e Library usage use module library autodoc htm1 e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc structure lpdocsrc src autodoc filesystem lpdocsrc src autodoc doctree lpdocsrc src autodoc index lpdocsrc src autodoc refsdb lpdocsrc src autodoc images lpdocsrc src autodoc settings lpdocsrc src comments fastformat lpdocsrc src autodoc ht
166. les include arguments intended for providing textual information This includes titles descriptions comments etc The type of this argument is a character string In order for the automatic generation of documentation to work correctly this character string should adhere to certain conventions See the description of the docstring 1 type grammar for details e Referring to variables In order for the automatic documentation system to work correctly variable names for example when referring to arguments in the head patterns of pred dec larations must be surrounded by an Gear command For example var VariableName should be used for referring to the variable VariableName which will appear then for matted as follows VariableName See the description of the docstring 1 type grammar for details 42 The Ipdoc Documentation Generator 4 3 Usage and interface assertions doc E 2 e Library usage The recommended procedure in order to make use of assertions in user programs is to include the assertions syntax library using one of the following declarations as appropriate module assertions use package assertions e Exports Predicates check 1 trust 1 true 1 false 1 e New operators defined gt 2 975 xfx 2 978 xfx dec1 1 1150 fx dec1 2 1150 xfx pred 1 1150 fx pred 2 1150 xfx prop 1 1150 fx prop 2 1150 xfx modedef 1 1150 fx calls 1 1150 fx calls 2 1150 xfx su
167. lgorithm The following properties should hold upon exit CommentType section 2 Section is a documentation string docstring 1 Usage 14 doc CommentType SubSection Description Insert a program subsection with name SubSection see program section command for more details Example doc subsection Auxiliary Definitions The following properties should hold upon exit CommentType subsection 2 SubSection is a documentation string docstring 1 Usage 15 doc PredName CommentText Description Provides an introductory comment for a given predicate function prop erty type etc denoted by PredName When generating documentation for the mod ule automatically the text in Text will be used as the introduction of the corre sponding predicate function description There should be at most one of these declarations per predicate function property or type Example doc doc 2 This declaration provides one of the main means for adding concept machine readable comments to programs The following properties should hold upon exit PredName is a Name Arity structure denoting a predicate name The Ipdoc Documentation Generator predname P A atm P nnegint A predname 1 CommentText is a documentation string docstring 1 Usage 16 doc CommentType ComnentText Description Documents a known bug or planned improvement in the module or appl
168. m analyzers of ciaopp They are used by ciaopp on output and they can also be used as properties in assertions 8 1 Usage and interface native_props e Library usage use module library assertions native props or also as a package use package nativeprops Note the different names of the library and the package e Exports Properties clique 1 clique 1 1 constraint 1 covered 1 covered 2 exception 1 exception 2 fails 1 finite solutions 1 have choicepoints 1 indep 1 indep 2 is det 1 linear 1 mshare 1 mut exclusive 1 no choicepoints 1 no exception 1 no exception 2 no signal 1 no signal 2 non det 1 nonground 1 not covered 1 not fails 1 not mut exclusive 1 num solutions 2 solutions 2 possibly fails 1 possibly nondet 1 relations 2 sideff hard 1 sideff pure 1 Sideff soft 1 signal 1 signal 2 signals 2 size 2 size 3 size 1b 2 size 0 2 size ub 2 size metric 3 size metric 4 steps 2 steps 1b 2 steps o 2 Steps ub 2 tau 1 terminates 1 test type 2 throws 2 user output 2 e Other modules used System library modules terms_check terms_vars sort lists streams file_utils system Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support internals P 8 2 Documentation on exp
169. m tex REPRE RE Ce ere 81 notsrads I ODPOB ae orsi de EDEN EF en OXON Iren 81 not mut exclusive 1 prop 43 2 eee re Eus 82 tuirn solutions 2 prop vd secre Er REPRE ERE 82 solutions 72 EE 82 possibly fails 1 EE 82 possibly nondet 1 prop 83 relations 2 prop Sua iere ED ia eee rae eee re es 83 sideff hard 1 prop varada EH 83 sidelt pure sl prop riot in ta 83 sideff soft b BEOD bi 83 Signal EE 83 im ual 2 plop cu oae titer sodes rt Ra tete es 83 GE EE 84 9126 2 PTOP ud neriie eee EE 84 SIZE JA PEOD sae ieee ed du n Sept nU ao bou dede 84 126 1h72 PrOD EE 84 SEO PrOD si aaiae hi ea 84 EE EE 84 vale Prop lt i E DO ena 84 size metric 4 prop v2 shove ae Exc e pre CERES 84 A 2 Prop ao bt bere tte tee wes ends 85 steps lb 2 prop ek EEN ert ed E Ert a 85 Steps 072 EE 85 steps ub 2 prop ge Eer 85 e A A 85 terminates 1 EE 86 test type 2 y AA eoe c E Le c f 86 E PrOp h Ee dee 86 user output 2 CDROB S e eis e RR ERE X RUM AE IRSE 86 instance 2 EE 86 9 M tacproperties sei ex RE E ES 87 9 1 Usage and interface meta props ee eee eee eee 87 9 2 Documentation on exports meta Dropel sees 87 calla PrOD cio seio debet EE 87 Prop 7 EE 87 tegtyp 2 DEOD uc err 20 preset Pon o orae 88 9 3 Documentation on multifiles neta Dropel s 88 le pred ina ceri HEIN Pearse IU e e 88 9 4 Documentation on internals meta Dropsl sees 88 Drop abs CL Prop eri wae Sec AERE REF RARE US 88
170. machine readable they can also be used to generate printed or on line documentation automatically using the 1pdoc automatic documentation generator These textual comments are meant to be complementary to the formal statements present in assertions see the assertions library 3 1 Usage and interface comments 3 e Library usage It is not necessary to use this library in user programs The recommended procedure in order to make use of the doc 2 declarations that this library defines is to include instead the assertions package which provides efficient support for all assertion and comment related declarations using one of the following declarations as appropriate module assertions use package assertions e Exports Predicates doc_id_type 3 Properties docstring 1 stringcommand 1 Regular Types version_descriptor 1 filetype 1 e Other modules used System library modules strings Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 3 2 Documentation on exports comments docstring 1 PROPERTY Defines the format of the character strings which can be used in machine readable com ments doc 2 declarations and assertions These character strings can include certain formatting c
171. ments included in the source file need to be written using the Ciao system assertion language A simple compatibility library is available to make traditional con straint logic programming systems ignore these assertions and comments allowing normal treat ment of programs documented in this way The documentation is currently generated in HTML or texinfo format From the texinfo output printed and on line manuals in several formats dvi ps info etc can be easily generated automatically using publicly available tools 1pdoc can also generate man pages Unix man page format as well as brief descriptions in html or emacs info formats suitable for inclusion in an on line index of applications In particular lpdoc can create and maintain fully automatically WWW and info sites containing on line versions of the documents it produces The 1pdoc manual and the Ciao system manuals are generated by 1pdoc lpdoc is distributed under the GNU general public license Note lpdoc is fully supported on Linux Mac OS X and other Un x like systems Due to the use of several Un x related utilities some documentation back ends may require Cygwin under Win32 This documentation corresponds to version 3 0 2011 7 7 16 33 15 CEST The Ipdoc Documentation Generator Chapter 1 Introduction 3 1 Introduction lpdoc is an automatic program documentation generator for C LP systems lpdoc generates a reference manual automatically from one or more
172. ml template lpdocsrc src distpkg download lpdocsrc src autodoc html resources System library modules lists dict system file utils Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support Y 21 2 Documentation on multifiles autodoc_html autodoc escape string hook 5 PREDICATE No further documentation available for this predicate The predicate is multifile autodoc_rw_command_hook 4 PREDICATE The predicate is multifile Usage autodoc_rw_command_hook Backend DocSt Command NewCommand The following properties should hold at call time Backend is a supported backend backend_id 1 docstate DocSt docstate 1 Intermediate tree representation for documentation doctree 1 Intermediate tree representation for documentation doctree 1 autodoc finish hook 1 PREDICATE No further documentation available for this predicate The predicate is multifile 140 The Ipdoc Documentation Generator autodoc gen alternative hook 2 PREDICATE No further documentation available for this predicate The predicate is multifile Chapter 22 Resource Handling for the HTML Backend 141 22 Resource Handling for the HTML Backend Author s Jose F Morales 22 1 Usage and interface autodoc html resources 3 e Library usage
173. n 1 4 v 1 v n are unique variables which are called parametric variables 5 Each body i is of the form 1 t z where z is one of the term variables and t is a regular type expression 2 q y t 1 t m where m gt 0 q m is a parametric type functor not in the set of functors 7 2 2 3 t 1 t mare regular type expressions and y is a term variable 6 Each term variable occurs at most once in the clause s body and should be as the first argument of a literal A regular type expression is either a parametric variable or a parametric type functor applied to some of the parametric variables A parametric type functor is a regular type defined by a regular program or a basic type Basic types are defined in Chapter 7 Basic data types and properties page 61 The set of regular types is thus a well defined subset of the set of properties Note that types can be used to describe characteristics of arguments in assertions and they can also be executed called as any other predicates Usage regtype AssertionBody The following properties should hold at call time AssertionBody is an assertion body assrt_body 1 regtype 2 DECLARATION This assertion is similar to a regtype 1 assertion but it is explicitely qualified Non qualified regtype 1 assertions are assumed the qualifier check Note that checking regular type definitions should be done with the ciaopp preprocessor Usage AssertionStat
174. n Goal E Description Calls of the form Goal do not throw exception E no signal 1 PROPERTY Meta predicate with arguments no_signal goal Usage no signal Goal Description Calls of the form Goal do not send any signal no signal 2 PROPERTY Meta predicate with arguments no signal goal Usage no signal Goal E Description Calls of the form Goal do not send the signal E non det 1 PROPERTY non det X All calls of the form X are non deterministic i e produce several solutions Meta predicate with arguments non det goal Usage non det X Description All calls of the form X are non deterministic nonground 1 PROPERTY Usage nonground X Description X is not ground The following properties should hold globally This predicate is understood natively by CiaoPP as not ground X native 2 not covered 1 PROPERTY not covered X There is some call of the form X for which there is no clause whose test succeeds DLGH97 Usage not covered X Description Not all of the calls of the form X are covered ER The Ipdoc Documentation Generator not fails 1 PROPERTY not fails X Calls of the form X produce at least one solution or do not terminate DLGH97 Meta predicate with arguments not fails goal Usage not failsQO Description All the calls of the form X do not fail The following properties hold globally This predicate is understood natively by Ci
175. n examples for testing the automatic documentation system 11 1 Usage and interface example module N e Library usage use module library example module e Exports Predicates q 2 r 1 p 1 p 5 u 3 w 1 mytype 1 t 5 s 1 q 1 Properties long 1 Regular Types bar 1 baz 1 aorb 1 tree_of 2 list_or_aorb 2 Multifiles p 3 e Other modules used Files of module user foo System library modules assertions native_props engine basic_props lists Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support y 11 2 Documentation on exports example_module bar 1 REGTYPE Usage bar X Description X is an acceptable kind of bar baz 1 REGTYPE A regular type defined as follows baz a baz b 96 The Ipdoc Documentation Generator aorb 1 REGTYPE A regular type defined as follows aorb a aorb b tree of 2 REGTYPE A regular type defined as follows tree of 1 void tree of T tree 1 2 3 call T 1 tree of T 2 tree of T 3 list or aorb 2 REGTYPE A regular type defined as follows list or aorb T 1 list T 1 list or aorb T 1 aorb 1 q 2 PREDICATE The predicate is of type dynamic Usage 1 The following properties should
176. ng A reference will be included in the usage index Chapter 3 Documentation Mark up Language and Declarations 29 filetfilename filename is the name of a file and will be printed in fixed width typewriter like font This command should be used when referring to a file in a documentation string A reference will be included in the usage index Qvarivarname varname is the name of a variable and will be formatted in an emphasized font Note that when referring to variable names in a pred 1 declara tion such names should be enclosed in var commands for the automatic documentation system to work correctly Referencing commands The following commands are used to introduce bibliographic citations and references to sections urls email addresses etc cite keyword keyword is the identifier of a bibliographic entry Such entry is assumed to reside in on of a number of bibtex files bib files A reference in brackets is inserted in the text an the full reference is included at the end with all other references in an appendix For example cite iso prolog will introduce a citation to a bibliographic entry whose keyword is iso prolog The list of bibliography files which will be searched for a match is determined by the BIBFILES variable of the 1pdoc SETTINGS file ref section title introduces at point a reference to the section or node section title where section title must be the exact text of the section title
177. ng Str representation of version Version except date version string 2 PREDICATE Usage version string Version Str Description Obtain the string Str representation of version Version including date insert show toc 3 PREDICATE Usage insert show toc RO DocSt R Description Insert the command to show the table of contents in a given doctree 1 The right place may be different depending on the chosen backend 17 3 Documentation on multifiles autodoc_doctree autodoc rw command hook 4 PREDICATE No further documentation available for this predicate The predicate is multifile autodoc escape string hook 5 PREDICATE No further documentation available for this predicate The predicate is multifile 128 The Ipdoc Documentation Generator Chapter 18 Handling the Document Structure 129 18 Handling the Document Structure Author s Jose F Morales 18 1 Usage and interface autodoc structure 3 e Library usage use module library autodoc_structure e Exports Predicates docstr node 4 clean_docstr 0 parse_structure 0 standalone docstr 1 get_ mainmod 1 get mainmod spec 1 all component specs 1 e Other modules used Application modules lpdocsrc src autodoc settings System library modules filenames aggregates terms make make rt Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions
178. ng commands The following commands are used to mark certain words or sentences in the text as concepts names of predicates libraries files etc The use of these commands is highly recommended since it results in very useful indices with little effort 28 The Ipdoc Documentation Generator index text text will be printed in an emphasized font and will be included in the concept definition index and also in the usage index This command should be used for the first or definitional appearance s of a concept The idea is that the concept definition index can be used to find the definition s of a concept cindex text text will be included in the concept index and also in the usage index but it is not printed This is used in the same way as above but allows sending to the index a different text than the one that is printed in the text concept tert text will be printed in a normal font This command is used to mark that some text is a defined concept In on line manuals a direct access to the corresponding concept definition may also be generated A pointer to the place in which the concept command occurs will appear only in the usage index pred predname predname which should be in functor arity form is the name of a pred icate and will be printed in fixed width typewriter like font This com mand should be used when referring to a predicate or a property or type in a documentation string A reference wil
179. ng properties hold globally iso G is side effect free sideff 2 Usage iso G Description Complies with the ISO Prolog standard deprecated 1 PROPERTY Specifies that the predicate marked with this global property has been deprecated i e its use is not recommended any more since it will be deleted at a future date Typically this is done because its functionality has been superseded by another predicate Meta predicate with arguments deprecated goal General properties deprecated G The following properties hold globally deprecated G is side effect free sideff 2 Usage deprecated G Description DEPRECATED not further inst 2 PROPERTY Meta predicate with arguments not further inst goal General properties not further inst G V The following properties hold globally not further inst G V is side effect free sideff 2 Usage not further inst G V Description V is not further instantiated The Ipdoc Documentation Generator sideff 2 sideff G X PROPERTY Declares that G is side effect free if its execution has no observable result other than its success its failure or its abortion soft if its execution may have other observable results which however do not affect subsequent execution e g input output or hard e g assert retract Meta predicate with arguments sideff goal General properties sideff G X The following properties hold globally Thi
180. nging s rrcucrecrerrrreere 17 page style changing 000 17 paragraph break essani cuado rinii e E ee eee 27 parametric property sseeeeee eee 88 parametric regular type abstractions 88 parametric type functor 60 parts in a large document 23 parts in large documents 38 179 planned improvement esses eeeeses 36 pred assertion s euer i I a Roe Ei 42 43 program section esn ed prete ERU PR SE 35 program subesechon eese 35 Prolog Clos tei 56 eio RI cto 15 prop assertion oo oooooooccocorrooo 45 46 properties of computations esses eese 5T properties of execution states o o o ooo 5T properties baste 61 properties native ce eee eee eee 77 property abstraction 0 0 eee eee eee 88 R TELETENCES si oy eo Bh ween ed ee ee AE Whe be oe 29 regtype assertion i eve mee eee ele 60 regular type expression 00 60 running unit tests 0 cee eee eee ee 105 S Sector aco uS Y bar Erie Nar atis duis 27 Ge De EE 29 SETTINGS plisin d NEEN Ed AE 15 sharing pieces of test 30 sharing Sets x aa DURER OUR S 80 soft side effects eese 83 space extra Dnes 2 0 cece eee eee eee 27 spcae horizontal fill o o o ooooooo oooo 27 special characters 0 cc eee e eee teens 30 Strong Eegeregie eats 27 Subsectlomnaz ce suu rx ro ee d 27 subtitle nio AA e a 33 success assertion ooooooooccoro
181. ntation on a basic set of properties types etc which are predefined in the Ciao basic props regtypes native props and meta props libraries These properties and any others defined by the user or in other Ciao libraries can be used in program assertions e Documentation on the formatting commands that can be embedded in comments This document is also an internals manual providing information on how the different internal parts of lpdoc are connected which can be useful if new capabilities need to be added to the system or its libraries are used for other purposes To this end the document also provides e The documentation for the autodoc automatic documentation library which provides the main functionality of 1pdoc e Documentation on the predicates that define the conversion formats used texinfo and others and which are in the autodocformats library All of the above have been generated automatically from the assertions in the corresponding sources and can also be seen as examples of the use of 1pdoc Some additional information on 1pdoc can be found in Her00 1 2 lpdoc operation source and target files The main input used by 1pdoc in order to generate a manual are Prolog source files Basically lpdoc generates a file in the GNU texinfo format with a texi ending for each Prolog file see The GNU Texinfo Documentation System manual for more info on this format The Prolog files must have a p1 ending If the
182. o 14 1 Installing the source distribution Ipdoc e Defore installing 1pdoc you may want to read Section 14 2 Other software packages re quired Ipdoc page 107 Make sure that emacs is installed in your system e Uncompress using gunzip and unpackage using tar xpf the distribution in a suitable directory This will create a new directory called 1pdoc as well as a link 1pdoc X Y to this directory where X Y is the version number of the distribution The p option in the tar command ensures that the relative dates of the files in the package are preserved which is needed for correct operation of the Makefiles e Enter the newly created directory and if needed edit the file LPDOCSETTINGS pl in a text editor but in general the default options works well edit the one in that directory not the ones in the subdirectories e Decide which Prolog CLP system you will use for compiling 1pdoc actually currently only Ciao is supported but porting to e g SICStus Prolog should not be too diffi cult and modify the first part of the LPDOCSETTINGS p1 file accordingly The DOCDIR directory should not be an existing info directory since this will overwrite the dir file in that directory e Select the directories in which you want the 1pdoc binaries libraries and documents installed by setting the corresponding variables in LPDOCSETTINGS pl e Type lpmake all This should create the 1pdoc executable and compile related libraries
183. o in Emacs or info in a shell there are two requirements e This directory must contain a dir index The first part of the process can all be done automatically by setting the docdir variable in the SETTINGS p1 file to this directory including the infoindex option in docformats and typing lpdoc install This will install the info manual in directory docdir and update the dir file there Ipdoc uninstall does the opposite eliminating also the manual from the index e The directory must be added to the info path list The easiest way to do this is to set the INFOPATH environment variable For example assuming that we are installing the info manual in home clip public_html lpdoc_docs and that usr info is the common info directory for csh in cshrc setenv INFOPATH usr info home clip public html lpdoc docs Adding the directory to the info path list can also be done within Emacs by including the following line in the Emacs file defun add info path newpath setq Info default directory list cons expand file name newpath Info default directory list add info path home clip public html lpdoc docs add info path usr info However this has the disadvantage that it will not be seen by the standalone info command Automatic direct on line access to the information contained in the info file e g going au tomatically to predicate descriptions by clicking on predicate names in programs in an Emacs buffer can be easily im
184. o predicate arguments in assertions The meaning of this application is that the call and success properties defined by the mode hold for the argument to which the mode is applied Thus a mode is conceptually a property macro The syntax of mode definitions is similar to that of pred declarations For example the following set of assertions modedef A nonvar A A is bound upon predicate entry pred p A B integer A gt ground B is equivalent to pred p A B nonvar A integer A gt ground B A is bound upon predicate entry Usage modedef AssertionBody The following properties should hold at call time AssertionBody is an assertion body assrt_body 1 decl 1 DECLARATION This assertion is similar to a pred 1 assertion but it is used for declarations instead than for predicates Usage decl AssertionBody The following properties should hold at call time AssertionBody is an assertion body assrt_body 1 decl 2 DECLARATION This assertion is similar to a decl 1 assertion but it is explicitely qualified Non qualified decl 1 assertions are assumed the qualifier check Usage AssertionStatus decl AssertionBody The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is an assertion body assrt_body 1 48 The Ipdoc Documentation Generator doc 2 DECLARATION Usage doc Pred Comment
185. ocSt doctree prepare docst translate and write 3 No further documentation available for this predicate doctree to rawtext 3 Usage doctree to rawtext X DocSt Y Description Y is a simplified raw text representation of the X Call and exit should be compatible with Intermediate tree representation for documentation docstate DocSt Y is a string a list of character codes doctree translate and write 3 No further documentation available for this predicate escape string 4 Usage doctree 1 docstate 1 doctree 1 PREDICATE doctree 1 docstate 1 PREDICATE PREDICATE doctree 1 docstate 1 string 1 PREDICATE PREDICATE Description Escapes needed characters in input string as needed for the target for mat The following properties should hold upon exit Argi is currently instantiated to an atom Arg2 is a string a list of character codes docstate Arg3 Arg4 is a string a list of character codes is version 1 No further documentation available for this predicate atom 1 string 1 docstate 1 string 1 PREDICATE Chapter 17 Documentation Abstract Syntax Tree 127 version patch 2 PREDICATE No further documentation available for this predicate version date 2 PREDICATE No further documentation available for this predicate version numstr 2 PREDICATE Usage version numstr Version Str Description Obtain the stri
186. of the html and info index head and tail files Manuel Hermenegildo Made pointers relative in library html templates Manuel Hermenegildo e Bug fixes and other minor improvements Declarations now documented properly even if they have the same name and arity as a predicate Manuel Hermenegildo Accented i s now translate correctly in html Manuel Hermenegildo Fixed a funny installation quirk while we want to install LPdoc in the Ciao group the manuals produced by LPdoc should be installed in the LPdoc group Manuel Hermenegildo Now using lpdoclib path alias Manuel Hermenegildo Fixed bug in ordering of html indices in recent Linux versions related to varying file listing order depending on locale Manuel Hermenegildo Version 1 9 1999 7 8 18 19 43 MEST In this release the name of the application has changed to 1pdoc e New commands begin cartouche and end cartouche commands now supported foonote command now supported New gmake htmlview command makes a running netscape visit the gen erated html manual Suggested by Per Cederberg New gmake distclean command intended for software distributions Leaves the generated documents and eliminates all intermediate files in cluding texic texi files Adobe pdf format now supported as a valid target Unfortunately embed ded eps figures are not supported at this time in pdf output The second argument of comment hide and comment doinclude
187. ogramming o ooooooc ooo o o 19 load vpaths 0 erre CiN deaa llle 131 132 locate and convert image 4 161 log of changes ecrire np ieoor cece cece ene enee 36 TEE 104 longp 4 voe qeu eu ab 95 97 98 lpdoc 1 3 4 5 8 15 16 17 18 19 20 21 22 23 24 25 29 37 41 48 52 56 89 107 108 lpdoc helpz gouvirs pi xe deua 16 lpdoc all 3E Fa BS X reden 16 17 19 IpPdOcEXAMPlOS enee a 89 Ipdoc Stallone 107 lpdoc option luariici ri VEA 131 LpdocareierctLautodoc mo 141 lpdocsrc src autodoc aux 137 145 157 161 lpdocsrc src autodoc bibrefs 153 lpdocsrc src autodoc doctree 112 115 137 139 145 151 153 157 lpdocsrc src autodoc filesystem 112 115 123 137 139 141 151 153 161 lpdocsrc src autodoc htm1 123 lpdocsrc src autodoc html resources 112 139 lpdocsrc src autodoc html template 139 lpdocsrc src autodoc images 137 139 145 lpdocsrc src autodoc index 112 115 123 137 139 lpdocsrc src autodoc man 123 lpdocsrc src autodoc_parse 112 115 157 lpdocsrc src autodoc refsdb 112 115 123 139 151 157 lpdocsrc src autodoc settings 112 115 123 129 137 139 141 143 147 157 159 161 lpdocsrc src autodoc state 112 123 137 139 145 147 151 153 157 161 lpdocsrc src autodoc structure 112 115 123 137 139 147 151
188. old at call time AssertionBody is a call assertion body c_assrt_body 1 This type of assertion provides information about the answers that an exported predicate provides for external calls It is identical syntactically to a success 1 assertion However it describes only external answers i e answers to the exported predicates of a module from outside the module or answers to the predicates in a non modular file from other files or the user The described answers may be conditioned to a particular way of calling the predicate E g exit length L N list var gt list integer Usage exit AssertionBody The following properties should hold at call time AssertionBody is a predicate assertion body s_assrt_body 1 DECLARATION DECLARATION DECLARATION Chapter 4 The Ciao assertion package 4T exit 2 DECLARATION exit assertion This assertion is similar to an exit 1 assertion but it is explicitely qualified with an assertion status Non qualified exit 1 assertions are assumed the qualifier check Usage AssertionStatus exit AssertionBody The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is a predicate assertion body s assrt body 1 modedef 1 DECLARATION This assertion is used to define modes A mode defines in a compact way a set of call and success properties Once defined modes can be applied t
189. ommands 26 The Ipdoc Documentation Generator e All printable characters are admissible in documentation strings except and To produce these characters the following escape sequences should be used respectively 60 Of and QJ e In order to allow better formatting of on line and printed manuals in addition to normal text certain formatting commands can be used within these strings The syntax of all these commands is Q command followed by either a space or or command body where command is the command name and body is the possibly empty command body The set of commands currently admitted can be found in the documentation for the predicate stringcommand 1 Usage docstring Text Description Text is a documentation string stringcommand 1 PROPERTY Defines the set of structures which can result from parsing a formatting command admis sible in comment strings inside assertions In order to make it possible to produce documentation in a wide variety of formats the command set is kept small The names of the commands are intended to be reminiscent of the commands used in the LaTeX text formatting system except that 6 is used instead of A Note that would need to be escaped in ISO Prolog strings which would make the source less readable and in any case many ideas in LaTeX were taken from scribe where the escape character was indeed The following are the currently admissib
190. on available for this predicate main output name 2 PREDICATE No further documentation available for this predicate get subbase 3 PREDICATE Usage get subbase Base Sub SubBase Description SubBase is the name for the sub file Sub associated with Base The following properties should hold upon exit Base is the base name of a file without extension basename 1 Sub is an atom atm 1 SubBase is the base name of a file without extension basename 1 absfile to relfile 3 PREDICATE Usage absfile to relfile A Backend B Description Obtain the relative path w r t the output directory of an absolute file This is useful e g for URLs clean all 0 PREDICATE No further documentation available for this predicate clean docs no texi 0 PREDICATE No further documentation available for this predicate 150 The Ipdoc Documentation Generator clean all temporal 0 PREDICATE No further documentation available for this predicate clean intermediate 0 PREDICATE No further documentation available for this predicate clean tex intermediate 0 PREDICATE No further documentation available for this predicate Chapter 26 Indexing Commands Definition and Formatting 151 26 Indexing Commands Definition and Formatting Author s Jose F Morales This module defines index commands and formatting Note This part needs better documentation JEMC J 26 1 Usage and interface autodoc
191. on to Jose Morales Double quotes correctly translated to HTML Jose Morales author command to reference authors changed command referring to people by Cauthor in all the documentation Jose Morales Simplification of documentation setting files see the documentation for further details Jose Morales Using open for 1pdoc htmlview command in MacOS X Jose Morales Adding html and pdf formats as options for emacs customization of LPdoc html is the default one now Jose Morales Improved detection of external tools for image conversion Manuel Hermenegildo Added section name syntax auto correction This avoids wrong section names and thus dangling pointers in generated texinfo files Manuel Hermenegildo Document size more appropriate for current xdvi versions Manuel Hermenegildo Lpdoc no longer adds info filename suffix to infoindex entries since it breaks Debian s install info remove and goes against standard practice anyway Jose Luis Gonzalez Chapter 1 Introduction T Added option cv comment version that tells lpdoc if the file has ver sion comment Formatting of lpdoc version comments completed Edison Mera Improved handling of option values Added d option to Ipdoc that allows defining additional values in the argument Added options 1 and m that are similar to the corresponding lpmake options Edison Mera e Support for in code sections experimental Latex like font lock highlight
192. op level of the source directory of the application To this end an INSTALL p1 file as follows can be constructed use package assertions doc filetype application 4 4 forces file to be documented as an application doc title Installation instructions doc module include INSTALLATION 1pdoc Then the ascii INSTALLATION file can be generated by simply running lpdoc ascii in a directory with a SETTINGS pl file where MAIN is set to INSTALLATION pl 2 9 Troubleshooting These are some common errors which may be found using 1pdoc and the usual fix e Sometimes messages of the type gmake No rule to make target myfile texic needed by main texic Stop appear i e in the case above when running g make main target Since 1pdoc definitely knows how to make a texic file given a p1 file this means in make s language that it cannot find the corresponding pl file myfile pl in the case above The usual reason for this is that there is no directory path to this file declared in the SETTINGS p1 file e Messages of the type No room for a new write while converting from texi to dvi i e while running tex These messages are tex s way of saying that an internal area typically for an index is full This is normally because more indices were selected in the INDICES variable of the SETTINGS p1 file than the maximum number supported by the installed version of tex texinfo install
193. or Messages Author s Manuel Hermenegildo 28 1 Usage and interface autodoc errors 3 e Library usage use module library autodoc errors e Exports Predicates error_text 3 e Other modules used Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 28 2 Documentation on exports autodoc errors error text 3 PREDICATE No further documentation available for this predicate 156 The Ipdoc Documentation Generator Chapter 29 Resolution of Bibliographical References 157 29 Resolution of Bibliographical References Author s Manuel Hermenegildo original version Jose F Morales This module provides a predicate to resolve the bibliographical references found during the generation of documentation 29 1 Usage and interface autodoc_bibrefs S e Library usage use_module library autodoc_bibrefs e Exports Predicates resolve_bibliography 1 e Other modules used Application modules lpdocsrc src autodoc state lpdocsrc src autodoc doctree lpdocsrc src autodoc refsdb Ipdocsrc src autodoc_aux lpdocsrc src autodoc settings lpdocsrc src autodoc_parse System library modules dict aggregates terms file utils lists format make make rt make system_ extra
194. or this predicate docst message 2 PREDICATE No further documentation available for this predicate docst message 3 PREDICATE No further documentation available for this predicate docst opt 2 PREDICATE No further documentation available for this predicate docst currmod is main 1 PREDICATE No further documentation available for this predicate docst no components 1 PREDICATE Usage docst no components DocSt Description DocSt specify an empty list of components docst modname 2 PREDICATE Usage docst_modname DocSt ModName Description ModName is the name of the module that we are documenting labgen_init 1 PREDICATE No further documentation available for this predicate labgen_clean 1 PREDICATE No further documentation available for this predicate Chapter 16 Internal State for Documentation Generation labgen get 2 No further documentation available for this predicate docst mvar lookup 3 No further documentation available for this predicate docst_mvar_replace 4 No further documentation available for this predicate docst_mvar_get 3 No further documentation available for this predicate docst_mdata_clean 1 No further documentation available for this predicate docst_mdata_assertz 2 No further documentation available for this predicate docst_mdata_save 1 No further documentation available for this predicate docst_gdata 3 No further documentation a
195. ormer must be part of the module being documented There are also commands for inserting and scaling images includef filename the contents of filename will be included in line as if they were part of the string This is useful for common pieces of documentation or storing in a separate file long explanations if they are perceived to clutter the source file includeverbatim filename as above but the contents of the file are included verbatim i e com mands within the file are not interpreted This is useful for includ ing code examples which may contain s etc Note that this only means that the file will be included as is If you want the string to be represented in verbatim mode in the output you must sur round the includeverbatim filename with Cbegin verbatim and end verbatim includefact factname it is assumed that the file being documented contains a fact of the pred icate factname 1 whose argument is a character string The contents of that character string will be included in line as if they were part of the documentation string This is useful for sharing pieces of text between the documentation and the running code An example is the text which explains the usage of a command options etc includedef predname it is assumed that the file being documented contains a definition for the predicate predname The clauses defining this predicate will be included in line in verbatim mode as if they were part
196. orts native props clique 1 PROPERTY clique X X is a set of variables of interest much the same as a sharing group but X represents all the sharing groups in the powerset of those variables Similar to a sharing group a clique is often translated to ground 1 indep 1 and indep 2 properties Usage clique X Description The clique pattern is X The following properties should hold globally This predicate is understood natively by CiaoPP as clique X native 2 78 The Ipdoc Documentation Generator clique 1 1 PROPERTY clique 1 X X is a set of variables of interest much the same as a sharing group but X represents all the sharing groups in the powerset of those variables but disregarding the singletons Similar to a sharing group a clique 1 is often translated to ground 1 indep 1 and indep 2 properties Usage clique 1 X Description The 1 clique pattern is X The following properties should hold globally This predicate is understood natively by CiaoPP as clique 1 X native 2 constraint 1 PROPERTY constraint C C contains a list of linear in equalities that relate variables and int values For example A lt B 4 is a constraint while A lt BC 4 or A 3 4 B gt C are not Usage constraint C Description C is a list of linear equations The following properties hold globally This predicate is understood natively by CiaoPP native 1 covered 1 PROPERTY cover
197. p1 file does not define the predicates main O or main 1 it is assumed to be a library and it is documented as such the texi file generated will contain information on the interface e g the predicates exported by the file the name of the module and usage if it is a module 4 The Ipdoc Documentation Generator etc in addition to any other machine readable comments included in the file see Section 2 6 Enhancing the documentation being generated page 18 If on the contrary the file defines the predicates main O or main 1 it is assumed to be an application and no description of the interface is generated see Section 2 8 Some usage tips page 21 If needed files written directly in texinfo can also be used as input files for 1pdoc These files must have a src instead of texi ending This is needed to distinguish them from any automatically generated texi files Writing files directly in texinfo has the disadvantage that it may be difficult to adhere to all the conventions used by 1pdoc For example these files will be typically used as chapters and must be written as such Also the set of indices used must be the same that lpdoc is generating automatically Finally no bibliographic citations can be used Because of this and because in the future 1pdoc may be able to generate documentation in formats other than texinfo directly in which case these files would not be useful writing files in texinfo directly is discouraged Thi
198. ple it is more useful to write added support for pred assertions than modifying file so pred case is also handled 22 The Ipdoc Documentation Generator Sometimes one would like to write version comments which are internal i e not meant to appear in the manual This can easily be done with standard Prolog comments which lpdoc will not read An alternative and quite useful solution is to put such internal comments in patch changes e g 1 142 to 1 143 and put the more general comments which describe major changes to the user and should appear in the manual in version changes e g 1 1222 to 1 2220 Selecting the appropriate options in 1pdoc then allows including in the manual the version changes but not the patch changes which might on the other hand be included in an internals manual 2 8 8 Documenting Libraries and or Applications As mentioned before for each a pl file lpdoc tries to determine whether it is a library or the main file of an application and documents it accordingly Any combination of libraries and or main files of applications can be used arbitrarily as components or main files of a 1pdoc manual Some typical combinations are e Main file is a library no components A manual of a simple library which appears externally as a single module The manual describes the purpose of the library and its interface e Main file is on application no components A manual of a simple application e Main file is a libr
199. plemented via existing el packages such as word help written by Jens T Berger Thielemann jensthi ifi uio no word help may already be in your Emacs dis tribution but for convenience the file word help el and a word help setup el file providing suitable initialization are included in the 1pdoc library A suitable interface for word help is also provided by the ciao el Emacs file that comes with the Ciao system distribution i e if ciao el is loaded it is not necessary to load or initialize word help 2 7 3 Accessing man manuals The Unix man format manuals generated by lpdoc can be viewed using the Unix man com mand In order for man to be able to locate the manuals they should be copied to one of the subdirectories e g usr 1ocal man manl of one of the main man directories in the previous case the main directory would be usr local man As usual any directory can be used as as a man main directory provided it is included in the environment variable MANPATH Again this process can be performed automatically by setting the docdir variable in the SETTINGS p1 file to this directory and typing 1pdoc install Chapter 2 Generating Installing and Accessing Manuals 21 2 7 4 Putting it all together A simple powerful and very convenient way to use the facilities provided by lpdoc for automatic installation of manuals in different formats is to install all manuals in all formats in the same directory docdir and to choose a directory wh
200. pred Leg ae ae oe 152 27 Database of Documentation References 153 27 1 Usage and interface autodoc_refsdb 04 153 27 2 Documentation on exports autodoc_refsdb 153 compute refs and biblio 1 pred 153 prepare current refs 1 red 153 clean current refs 1 pred rs 153 secttree 1 regtype dis cava ac beber bi Perge t 154 secttree resolve 3 pred cece ee eee eee 154 28 Error Nessages cis ev ties bah EXER ES 155 28 1 Usage and interface Lautodoc errorsl suse 155 28 2 Documentation on exports autodoc_errors 155 error text 9 pred 55 das astute ier quet buda e 155 29 Resolution of Bibliographical References 157 29 1 Usage and interface autodoc_bibrefs 157 29 2 Documentation on exports autodoc_bibrefs 157 resolve bibliography 1 pred susasasununun 157 30 Auxiliary Definitions 159 30 1 Usage and interface autodoc aux 159 30 2 Documentation on exports autodoc_aux 159 read_file 2 Pr Poe e Rer ep ee Pes tes 159 aseit blank lines 2 pred ec e A gh 159 Sh exec 2 Pred Us oo reb eee o aae tea ded 159 31 Image Handling v Rt eee 161 31 1 Usage and interface autodoc Jnages sss 161 31 2 Documentation on exports autodoc images 161 locate and convert image 4 pred 161 clean image cache 0 pred eee 161 Referentes
201. predname 1 Usage 22 doc CommentType PredName 38 The Ipdoc Documentation Generator Description A different usage which allows the second argument of doc hide to bea list of predicate names The following properties should hold upon exit CommentType hide 2 PredName is a list of prednames list 2 Usage 23 doc CommentType FileType Description Provides a way of defining the intended use of the file This use is normally easily inferred from the contents of the file itself and therefore such a declaration is in general not needed The exception is the special case of include files and Ciao packages which are typically indistiguishable from normal user files i e files which are not modules but are however quite different in their form of use they are loaded via include 1 or use package 1 declarations instead of ensure loaded 1 and effect since they are included they export operators declarations etc Typically it is assumed by default that files which are not modules will be used as include files or packages Thus a doc 2 declaration of this kind strictly only needs to be added to user type files Example doc filetype user There is another special case the value part This filetype is used to flag files which serve as introductions to boundaries between major parts in large documents See Section 2 8 5 Splitting large documents into parts page 22 for details
202. ption Lis T or a nested list of Ts Note that if T is term this type is equivalent to term this fact explain why we do not have a nlist 1 type member 2 PROPERTY General properties member X L The following properties hold globally member X L is side effect free sideff 2 member X L is binding insensitive bind ins 1 member X L If the following properties hold at call time L is a list list 1 then the following properties hold globally member X L is evaluable at compile time eval 1 member _X L The following properties hold upon exit L is a list list 1 member X L If the following properties hold at call time L is currently ground it contains no variables ground 1 then the following properties hold upon exit X is currently ground it contains no variables ground 1 Usage member X L Description X is an element of L sequence 2 REGTYPE A sequence is formed with zero one or more occurrences of the operator 2 For example a b c is a sequence of three atoms a is a sequence of one atom Meta predicate with arguments sequence pred 1 General properties sequence S T TO The Ipdoc Documentation Generator The following properties hold globally sequence S T is side effect free sequence S T Ifthe following properties hold at call time S is currently ground it contains no variables T is currently ground it contains no variables
203. r this predicate modtype 1 modtype part modtype application modtype documentation modtype module modtype user modtype include modtype package Usage Description Represents the type of file being documented PREDICATE REGTYPE Chapter 16 Internal State for Documentation Generation 121 docst modtype 2 PREDICATE No further documentation available for this predicate get first loc for pred 3 PREDICATE No further documentation available for this predicate 122 The Ipdoc Documentation Generator Chapter 17 Documentation Abstract Syntax Tree 123 17 Documentation Abstract Syntax Tree Author s Manuel Hermenegildo original version Jose F Morales This module defines the intermediate tree representation doctree 1 for documentation and its related operations Note This part needs better documentation JFMC 17 1 Usage and interface autodoc_doctree f N e Library usage use module library autodoc_doctree e Exports Predicates cmd type 1 doctree is empty 1 is nonempty doctree 1 empty doctree 1 doctree insert end 3 doctree insert before section 3 doctree concat 3 doclink at 2 doclink is local 1 section prop 2 section select prop 3 doctree save 2 doctree restore 2 doctree simplify 2 doctree_putvars 5 doctree scan and save refs 2 doctree prepare docst translate and write 3 doctree to rawtext 3 doctree translate and write 3 escap
204. r which it was compiled this allows documenting Prolog systems other than that under which lpdoc was compiled The effect of putting a path in systempaths instead of in filepaths is that the mod ules and files in those paths are documented as system modules this is useful when documenting an application to distinguish its parts from those which are in the system libraries Set doc structure to be the document structure doc structure 1 For the rest of the settings in the SETTINGS p1 file you can simply use the default values indicated You may however want to change several of these doc mainopts 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 versions and patches or only patches authors changelog explanation of modes one sided printing two sided is the default etc See option comment 2 in autodoc or type 1pdoc help for a list of these options In the same way doc compopts sets options for the component files Currently these op tions are common to all component files but they can be different from doc mainopts The allowable options are the same as above docformat determines the set of formats dvi ps ascii html info manl in which the documentation should be generated by default when typing 1pdoc all Se lecting htmlindex and or infoindex requests the generation of parts of a mast
205. ram a meta interpreter for this purpose 6 2 Usage and interface regtypes doc p e Library usage use package regtypes Or module regtypes e New operators defined regtype 1 1150 fx regtype 2 1150 xfx e New declarations defined regtype 1 regtype 2 e Other modules used System library modules assertions assertions_props Internal engine modules term_basic 60 The Ipdoc Documentation Generator 6 3 Documentation on new declarations regtypes doc regtype 1 DECLARATION This assertion is similar to a prop assertion but it flags that the property being doc umented is also a regular type Regular types are properties whose definitions are regular programs see lelow This allows for example checking whether it is in the class of types supported by the regular type checking and inference modules A regular program is defined by a set of clauses each of the form p x v 1 v n body 1 body k where 1 x is a term whose variables which are called term variables are unique i e it is not allowed to introduce equality constraints between the variables of x For example pC X Y is valid but pC X X is not 2 in all clauses defining p n 1 the terms x do not unify except maybe for one single clause in which x is a variable 3 n gt 0 and p n is a parametric type functor whereas the predicate defined by the clauses is p
206. rated some formats are not very suitable for public installation For example the dvi format has the disadvantage that it is not self contained if images are included in the manual Typing 1pdoc uninstall in a doc directory will uninstall from docdir the manuals corresponding to the Makefile in that doc directory If a manual is already installed and changes in the number of formats being installed are desired 1pdoc uninstall should be made before changing the docformats variable and doing lpdoc install again This is needed in order to ensure that a complete cleanup is performed 2 6 Enhancing the documentation being generated The quality of the documentation generated can be greatly enhanced by including within the program text e assertions and e machine readable comments Assertions are declarations which are included in the source program and provide the com piler with information regarding characteristics of the program Typical assertions include type Chapter 2 Generating Installing and Accessing Manuals 19 declarations modes general properties such as does not fail standard compiler directives such as dynamic 1 op 3 meta predicate 1 etc When documenting a module 1pdoc will use the assertions associated with the module interface to construct a textual description of this interface In principle only the exported predicates are documented although any pred icate can be included in the documentation by explicitly r
207. rcoroomoooo 44 supported documentation formats 113 synopsis section of the man page 16 syntax of formatting commands 26 system modules 16 T test assertion ooocooccocooooo 44 45 105 texec assertion 00 eee eee ee 43 texinios ds rU EN eee elas 2E 111 texto files Ay cese pense eram pe Eee et 4 textual comments 25 thesis like style eet yo EO 17 titles eating A LAO dde Det 32 33 tr e Assertion jog e eb gee iting gon rS ER 49 trust assertions s o EE Xo CES 48 180 two sided iecit ect os p ob ecu By 16 typewriter like font 27 uit tests sit bdo A Soe MER ES 105 Universal Resource Locator ooooooooooo 29 UE cir RIDUC O eee Ed 29 EEN 29 usage of acommand esee 30 usage of the application 16 The Ipdoc Documentation Generator V verbatim text i orcnpeixue4j Ree iR x3 bey 27 Versio adu eru I ee Dig UA ee a Ried 29 version maintenance mode for packages 37 version number 36 W WWW address 0 0 ccc cence eens 29 Author Index Author Index A Anonymous Author 1 95 Anonymous Author 2 eene 95 D Daniel Cabeza o o ooooomomoo E Edison Mera F Francisco Dueno 77 103 105 41 57 77 87 181 G German Puebla mo 41 J Jose F Morales 111 115 123 129 131 137 139 141 143 145 147 151 153 157 159 161 M Manuel Hermenegildo 15 25 41 51 5
208. re no longer a problem space can be omitted Jose Morales Added and documented a new documentation filetype for some parts of the manual that contains only documentation That avoids the old trick of declaring a fake main O predicate Jose Morales Style for subtitle added automatically in texinfo it is emph in HTML it is normal text with smaller font The entries in subtitle extra are free form Jose Morales Bugs and changelog appear now in the global links in the HTML backend Jose Morales Merged code that documented pl and 1pdoc files Jose Morales No copyright section if no copyright comment Jose Morales Auxiliary documentation files ending in doc displayed incorrect names for the module ending in doc E g use package foo doc was dis played instead of use_package foo_doc Fixed Jose Morales In verbatim enviroments new line characters are removed from the begin ning Jose Morales Fix wrong use of erase 1 for clauses which resulted in segmentation fault when documentation generation failed Jose Morales Fixed image generation now uses png files for HTML Jose Morales New code for text escape fixed some problems like 1 operator not being displayed corretly in Info Jose Morales Colors for Prolog variables in HTML Jose Morales Added begin alert environment for alert messages like cartouche but in red Jose Morales Supporting command for umlaut in additi
209. red Ipdoc 107 PART II LPdoc Internals Manual 109 15 Documentation Generation Library 111 15 1 Usage and interface autodoc sg SEENEN EEN NEE 112 15 2 Documentation on exports Lautodoc 008 112 index comment 2 EE set er ee Ae 112 reset output dir db 0 pred o 0 oo oo ooo o 112 ensure output dir prepared 2 pred 112 get autodoc opts 3 pred cec oii pe 113 autodoc gen doctree 5 pred oooo ooooo 113 Imt infodir entry 3 pred 11 9 iet RES 113 autodoc compute grefs 3 pred 113 autodoc translate doctree 3 pred 113 autodoc finish 1 predecir ee edere he ton 114 autodoc gen alternative 2 pred 114 15 3 Documentation on multifiles autodoc 000 114 autodoc finish hook 1 pred o o oo oo o 114 autodoc gen alternative hook 2 pred 114 16 Internal State for Documentation Generation E udi ei aor cR ana ARCU SUA E EC Sa pcm dI d 115 16 1 Usage and interface autodoc statel 115 16 2 Documentation on exports autodoc state 115 supported options 1 prop aeo cies Ceres 115 option comment 2 red 116 backend id Al regtype isis IRE 116 backend ignores components 1 pred 116 backend alt format 2 pred oooooooo 117 top suf ix 2 pred gege 2 117 docstate l regtybe sedis re y Re e cds
210. reported Note that there is also an older package called rtchecks by David Trallero The advantage of this one is that it can be used independently of CiaoPP and also has updated functionality There are two main applications of run time checks e To improve debugging of certain predicates specifying some expected behavior that is checked at run time with the assertions e To avoid manual implementation of run time checks that should be done in some predicates leaving the code clean and understandable The run time checks can be configured using prolog flags Below we itemize the valid prolog flags with its values and a brief explanation of the meaning e rtchecks level e exports Only use rtchecks for external calls of the exported predicates e inner Use also rtchecks for internal calls Default e rtchecks trust e no Disable rtchecks for trust assertions e yes Enable rtchecks for trust assertions Default e rtchecks entry e no Disable rtchecks for entry assertions e yes Enable rtchecks for entry assertions Default e rtchecks exit e no Disable rtchecks for exit assertions e yes Enable rtchecks for exit assertions Default e rtchecks test e no Disable rtchecks for test assertions Default e yes Enable rtchecks for test assertions Used for debugging purposes but is better to use the unittest library e rtchecks inline e no Instrument rtchecks using call to library predicates present in rtchecks rt pl nativ
211. resentation format Any reference to the official version original version or how to obtain original versions of the document is preserved verbatim Any copyright notice in the document is preserved verbatim Also the title and author s of the original document should be clearly mentioned as such In the case of translations verbatim sentences mentioned in 6 are preserved in the language of the original document accompanied by verbatim translations to the language of the traslated document All translations state clearly that the author is not responsible for the translated work This license is included at least in the language in which it is referenced in the original version Whatever the mode of storage reproduction or dissemination anyone able to access a digitized version of this document must be able to make a digitized copy in a format directly usable and if possible editable according to accepted and publicly documented public standards Redistributing this document to a third party requires simultaneous redistribution of this licence without modification and in particular without any further condition or restriction expressed or implied related or not to this redistribution In particular in case of inclusion in a database or collection the owner or the manager of the database or the collection re nounces any right related to this inclusion and concerning the possible uses of the document after extraction from th
212. resented as 1 0e1000 and 1 0e1000 and Not a number which arises as the result of indeterminate operations represented as 0 Nan General properties 1t T The following properties hold globally flt T is side effect free flt T If the following properties hold at call time T is currently a term which is not a free variable then the following properties hold globally flt T is evaluable at compile time All calls of the form 1t T are deterministic flt T The following properties hold upon exit T is a float The following properties hold globally Indicates the type of test that a predicate performs analyisis Usage flt T Description T is a float The following properties hold globally This predicate is understood natively by CiaoPP num 1 The type of numbers that is integer or floating point General properties num T The following properties hold globally num T is side effect free num T is binding insensitive num T sideff 2 nonvar 1 eval 1 is_det 1 1t 1 Required by the nonfailure test type 2 native 1 REGTYPE sideff 2 bind ins 1 64 The Ipdoc Documentation Generator If the following properties hold at call time T is currently a term which is not a free variable nonvar 1 then the following properties hold globally num T is evaluable at compile time eval 1 All calls of the form num T are determin
213. rion EE 31 Qaa eeh e cci lo ESRB 31 QAA commande 31 Qae command AN WIRES Seyi oR dee 31 QAE commande 31 apl commande 28 author commande 29 Qb commazd eR hs See ees 31 begin alert commande 27 begin cartouche command 27 begin description command 26 begin displaymath command 30 Gbeginfenumerate command 26 begin itemize command 26 begin verbatim command 27 Qbf command o ck Reus ete aden bes 27 bullet commande 31 Qc command aere fate ed IR eke das 31 cindex commande 28 Qcite commande 29 comment Commande 26 concept commande 28 copyright commande 31 d command A ose tee e A a Sanae 31 decl commande 28 defmathemd 2 commande 30 defmathemd 3 commande 30 Qem commande 27 Qemail commande 29 Qend alert commande 27 end cartouche commande 27 end description commande 27 end displaymath command 30 177 end enumerate command 26 end itemize commande 26 end verbatim commande 27 file commande 29 footnote commande 27 D I command sisi seas a ose pet e 31 Ohfil eegne REUS us 27 Qi command ero ode Bex oot he 31 image Commande 30 include commande 30 includedef commande 30 includefact commande 30 includeverbatim commande 30 index commande 28 Qso command EE 31 item commande 26 27 OU command ebe II 31 key commande 27 Ql cOMmMANG A
214. rmi Term2 Description Termi is an instance of Term2 The following properties hold globally This predicate is understood natively by CiaoPP native 1 Chapter 9 Meta properties 87 9 Meta properties Author s Francisco Bueno This library allows the use of some meta constructs which provide for specifying properties of terms which are unknown at the time of the specification or expressed with a shorthand for the property definition i e without really defining it An example of such use is an assertion which specifies that any property holding upon call will also hold upon exit pred p X Prop X gt Prop X Another example is using shorthands for properties when documenting pred p X regtype X list list list See below for an explanation of such a regular type 9 1 Usage and interface meta_props E e Library usage use module library assertions meta props or also as a package use package metaprops Note the different names of the library and the package e Exports Properties call 2 prop 2 regtype 2 Multifiles callme 2 e Other modules used Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 9 2 Documentation on exports meta props call 2 PROP
215. rompt for an info file name Input the name of the info file generated by lpdoc main info and Emacs will open the manual in info mode There are several possibilities in order to install an info file so that it is publicly available i e so that it appears automatically with all other info manuals when starting info or typing C u M x info in Emacs e Installation in the common info directory 20 The Ipdoc Documentation Generator e Move the info file to the common info directory typically usr info usr local info This can be done automatically by setting the docdir vari able in the SETTINGS p1 file to this directory and typing lpdoc install Warning if you are installing in an info directory that is not maintained automatically by lpdoc make sure that you have not selected the infoindex option in docformats since this will overwrite the existing dir file e Add an entry to the info index in that directory normally a file in that directory called dir The manual should appear as part of the normal set of manuals available when typing M x info in Emacs or info in a shell See the Emacs manual for details e Installation in a different info directory you may want to place one or more manuals generated by 1pdoc in their own directory This has the advantage that 1pdoc will maintain automatically an index for all the 1pdoc generated manuals installed in that directory In order for such manuals to appear when typing M x inf
216. rop tree X regtype X is a tree Regular types can be used as properties to describe predicates and play an essential role in program debugging see the Ciao Prolog preprocessor ciaopp manual In this chapter we explain some general considerations worth taking into account when writing properties in general not just regular types 6 1 Defining properties Given the classes of assertions in the Ciao assertion language there are two fundamental classes of properties Properties used in assertions which refer to execution states i e calls 1 success 1 and the like are called properties of execution states Properties used in asser tions related to computations i e comp 1 are called properties of computations Different considerations apply when writing a property of the former or of the later kind Consider a definition of the predicate string concat 3 which concatenates two character strings represented as lists of ASCII codes string concat L L string concat X Xs L X NL string concat Xs L NL Assume that we would like to state in an assertion that each argument is a list of inte gers However we must decide which one of the following two possibilities we mean exactly the argument is instantiated to a list of integers let us call this property instantiated_ to intlist 1 or if any part of the argument is instantiated this instantiation must be compatible with the argument being a list of in
217. roperty in the property starterm 1 The idea is that each element of the 2 term corresponds to head argument position Several properties can be assigned to each argument position by grouping them in curly brackets The following is an example of a complex property in this format e integer list integer the first argument of the procedure or function or has the property integer 1 and the second one has the property list 2 with second argument integer e integer var list integer the first argument of the procedure or function or has the properties integer 1 and var 1 and the second one has the property list 2 with second argument integer Usage property starterm Props Description Props is either a term or several terms separated by 2 The main functor of each of those terms corresponds to that of the definition of a property and the arity should be one less than in the definition of such property All arguments of each such term are ground 54 The Ipdoc Documentation Generator complex goal property 1 REGTYPE complex goal property Props Props is a possibly empty complex goal property Such properties can be either a term or a conjunction of terms The main functor and arity of each of those terms corresponds to the definition of a property Such properties apply to all executions of all goals of the predicate which comply with the assertion in which the Props appear The arguments of the term
218. rtchecks doc d E e Library usage use package rtchecks Or module rtchecks e Other modules used Internal engine modules term basic arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support Chapter 13 Unit Testing Library 105 13 Unit Testing Library Author s Edison Mera This library provides an extension of the Ciao assertion language which allows writing unit tests The central idea is to use the assertion language to provide specifications of test cases for a given predicate The package also provides some special properties that are convenient when specifying unit tests and the required run time libraries In general a test assertion is written as follows test predicate A1 A2 An lt Precondition gt gt lt Postcondition gt lt Global properties gt t lt Comment gt Where the fields of the test assertion have the usual meaning in Ciao assertions i e they contain conjunctions of properties which must hold at certain points in the execution Here we give a somewhat more operational test oriented reading to these fields predicate n is the predicate to be tested Precondition is a goal that is called before the predicate being tested and can be used to generate values of the input parameters Postcondition is a
219. rtion coiere gai eena E RIS ipie 43 eege le sd a ERI See ar 42 43 Eege AANER E ER AE E 42 43 texi2dWl AA S T Ea 108 texi2htiml 2 EEN ali dE 108 exlndex i o ge ns atte TES UPS Audit 108 teximder do ede ste ARIA Ue 131 133 texinfo jussi n 1 3 4 16 17 21 24 111 TexinfOoi siticotis iege EN 108 t xinfo les cia dia oe ex Eee EREROUR 4 textual comments 210 kd luus di Gos wee 25 thesis like styles 10 os 17 thro ws 2 P e td oa a Rus 77 86 time stru ct 4 2222 a td ed Biden won a YR 39 times N on epp rea d idee Edit 105 title e mou ree hes 32 33 top suffix 2 v nbl dE AE 115 117 tree of 2 ostium ees 95 96 troubleshooting o o ooocooocoocmmo moo 15 true assertiom 4205 Lb Ue e UE 49 true ii EE 42 49 ET EE 48 tr st l i ipee ev PP Ree hel 42 48 try Sols N 2 doesvesbxkuecded eri wr wie 105 A cs scie ets IL OLIO uU ADS DIU ES 112 twossided uen app da 16 typeindex bc traci cas LP gg e DV peris 151 DY EE 3 typewriter like font 27 u 3 t estar usb tet Cd vete bere et 95 97 nit tests 5 0 da IO YR 105 unittest iaia wl etu ditt vermibus 105 Universal Resource Locator 29 Unix ite aeo E bailar ge ides Re 20 UR Dace A abd PE MN Raed bau idv 29 rl references EE 11 A BANS Dti EE se EE 29 USA DP 42 193 usage of the application 16 usage Section sv pL ecran 11 Usage EE 15 usage message 11 16 use module eee eh 23 Use packs Lia ER VETE
220. rty is used New option noisoline makes the textual explanation of the iso 1 property not appear in the description of the usage but the e ISO e symbol does appear Two new options nosysmods and noengmods selectively avoid listing the system or engine libraries used If there is no declaration for a predicate now a line is output with the name and arity and a simple comment saying that there is no further documentation available this has the great advantage that then it goes in the index and for example in ciao they get added to completion commands Now if a property or regtype declaration has no textual comment the actual definition is given first level only in the place where it is documented and a simple generic message where it is used Added noindent and iso commands Nicer spacing now when printing predicate names which are operators as well as modes etc Reporting of versions in libraries has been improved now both the global version and the last version in which the library itself was changed are reported Exported new declarations also documented now for include type files A module is now documented even if exports nothing at all Engine modules used now documented even if no other modules used was a reported bug Fixed indexing of names containing etc for newer versions of texinfo Tabs in verbatim modes now converted to a number of spaces 8 Not perfect but produces better output than leaving th
221. s Sty c m PPS eai E 107 dVips uhiide eie See tee ae a neas 7 108 AVA PSY Vacs tiie ere Ae te Sie Geld RES P 131 133 Ke 19 E Edison Meta ue e ERE erg 77 103 105 EE eS 11 36 39 107 108 EMACS SHA tmt e eet dias 15 18 19 20 emacs Ciao mode 36 Emacs accessing info files 19 Emacs generating manuals from 15 Emacs LPdoc mod cc s 2 uua a ado 15 ug E occ 108 187 email address mE he Pe e S 29 email addresses Leti lic Se 11 29 emphasis TACO nre risat eret Deep RM EDEN 27 empty doctree t 000 eee 123 124 encapsulated postscript 000 30 engine basic pDrops cess ee eee 95 ensure cache dir 1 sss 147 148 ensure Loaded esses 10 22 38 ensure output dir 1 ss 147 148 ensure output dir prepared 2 112 entry assertion oone e owed Y UE creme mes 46 entrfy 1 ue dv E am bie C bbs 42 46 54 en mnerated list 3 eb paw dv ps 26 environment variables leues 107 equiv 2 venu eaters PHELPS Qe ED Ens 61 75 errh ndle x ca oe EES de a aS 161 E EE 105 error free 1 eee e 61 75 error A S vebiuniexas eil 155 escape Seduenceg seen nn 26 escape String i esses 123 126 eval 1 61 62 63 64 65 66 67 68 69 70 71 72 73 75 99 101 example of lpdoc use 89 example module 0 cece eee eee 95 ezceptionierroria bi 105 exception 4d EA d v RA 77 78 EE 77 78 exceptions 25 42 51
222. s are obtained when documenting code organized as a series of libraries and with a well designed module structure e texinfo supports only a limited number of indices Thus if you select too many indices in the SETTINGS pl file you may exceed texinfo s capacity which it will signal by saying something like No room for a new write e The GNU info format requires all nodes chapters sections etc to have different names This is ensured by 1pdoc for the automatically generated sections by appending the module or file name to all section headings However care must be taken when writing section names manually to make them different For example use lpdoc usage instead of simply Usage which is much more likely to be used as a section name in another file being documented e Also due to a limitation of the info format do not use or or in section chapter etc headings e The character in names may sometimes give problems in indices since current versions of texinfo do not always handle it correctly 2 8 2 Writing comments which document version patch changes When writing version comments doc version it is useful to keep in mind that the text can often be used to include in the manual a list of improvements made to the software since the last time that it was distributed For this to work well the textual comments should describe the significance of the work done for the user For exam
223. s eL REL I Vets x dn 95 97 packages un sene boos ae CR em P Edo 22 38 page numbering changing 16 page size changing cece eeaee 17 Global Index page style changing 17 paragraph break i 6c cece cc eee 27 parametric property sese 88 parametric regular type abstractions 88 parametric type functor sess ss 60 parse structure 0 i nl dl acl 129 parts in a large document 23 parts in large docunents s 38 pdf generations ucla wie de RR ERA Pass 7 D EN ease cease Rea ea were et 8 POLE o d PD Eh pie E 108 pdfview l A EEN ule 131 132 pe type l oag cnp P malted qe 61 76 Pedro LopeZ ii RPM HIER eee de 57 77 POT EE 108 EE EE 143 planned improvement cece eae 36 possibly Zails t 77 82 possibly nondert i oo 77 83 pred assertiOn mica DV eee do os 42 43 pred 4 centies 29 42 43 44 45 47 51 55 EE 42 43 predfunctor l luxe ES REALES 51 56 predicatel ie at Db b UTC bars 104 predicate m rieut iori v Re ee Meese et 105 prednam e 1 2 92 su 36 37 52 61 71 72 prepare current refs 1 153 154 prepare mathjax 0 sse eee eee 141 prepare web skel 1 sess ess 141 program assertions esee ess 41 program Section esee 35 program subsection 0c eee eee eee 35 LTE 3 16 22 107 Prolog source filles 3 Prolog 0180 das adds 15 prolog flags 25 42 51 61 77
224. s facility was added mainly to be able to reuse parts of manuals which were already written in texinfo Note that if a stand alone file needs to be written i e a piece of documentation that is not associated to any pl file it can always be written as a dummy pl file De one that is not used as code but which contains machine readable comments A manual can be generated either from a single source file pl or src or from a set of source files In the latter case then one of these files should be chosen to be the main file and the others will be the component files The main file is the one that will provide the title author date summary etc to the entire document In principle any set of source files can be documented even if they contain no assertions or comments However the presence of these will greatly improve the documentation see Section 2 6 Enhancing the documentation being generated page 18 If the manual is generated from a single main file i e component 1 defined below is empty then the document generated will be a flat document containing no chapters If the manual is generated from a main file and one or more components then the document will contain chapters The comments in the main file will be used to generate the introduction while each of the component files will be used to generate a separate chapter The contents of each chapter will be controlled by the contents of the corresponding component
225. s hold upon exit T is a list Usage list L Description L is a list list 2 list L T L is a list and for all its elements T holds Meta predicate with arguments list pred 1 General properties list L T The following properties hold globally list L T is side effect free list L T If the following properties hold at call time L is currently ground it contains no variables T is currently ground it contains no variables then the following properties hold globally list L T is evaluable at compile time list X T The following properties hold upon exit X is a list Usage list L T Description L is a list of Ts nlist 2 Meta predicate with arguments nlist pred 1 General properties nlist L T sideff 2 ground 1 eval 1 is_det 1 list 1 REGTYPE sideff 2 ground 1 ground 1 eval 1 list 1 REGTYPE Chapter 7 Basic data types and properties 69 The following properties hold globally nlist L T is side effect free sideff 2 nlist L T If the following properties hold at call time L is currently ground it contains no variables ground 1 T is currently ground it contains no variables ground 1 then the following properties hold globally nlist L T is evaluable at compile time eval 1 nlist X T The following properties hold upon exit X is any term term 1 Usage nlist L T Descri
226. s in Props are implicitely augmented with a first argument which corresponds to a goal of the predicate of the assertion in which the Props appear For example the assertion comp var A not further inst A has property not further inst 1 as goal property and establishes that in all executions of var A it should hold that not further inst var A 4A Usage complex goal property Props Description Props is either a term or a conjunction of terms The main functor and arity of each of those terms corresponds to the definition of a property A first implicit argument in such terms identifies goals to which the properties apply nabody 1 PROPERTY Usage nabody ABody Description ABody is a normalized assertion body dictionary 1 REGTYPE Usage dictionary D Description D is a dictionary of variable names c assrt body 1 REGTYPE This predicate defines the different types of syntax admissible in the bodies of ca11 1 entry 1 etc assertions The following are admissible Pr CP CO where fields between are optional e CP is a possibly empty complex argument property complex arg property 1 which applies to the calls to the predicate e CO is a comment string docstring 1 This comment only applies if the possibly empty properties given for calls in the assertion hold The usual formatting com mands that are applicable in comment strings can be used see stringcommand 1 T
227. s predicate is understood natively by CiaoPP sideff G X is side effect free Usage sideff G X Description G is side effect X If the following properties hold at call time X is an element of free soft hard regtype 1 Meta predicate with arguments regtype goal General properties regtype G The following properties hold globally regtype G is side effect free Usage regtype G Description Defines a regular type native 1 Meta predicate with arguments native goal General properties native P The following properties hold globally native P is side effect free Usage native Pred Description This predicate is understood natively by CiaoPP native 2 Meta predicate with arguments native goal General properties native P K The following properties hold globally native P K is side effect free Usage native Pred Key Description This predicate is understood natively by CiaoPP as Key native 1 sideff 2 member 2 PROPERTY sideff 2 PROPERTY sideff 2 PROPERTY sideff 2 Chapter 7 Basic data types and properties 75 no_rtcheck 1 PROPERTY Meta predicate with arguments no_rtcheck goal General properties no_rtcheck G The following properties hold globally no_rtcheck G is side effect free sideff 2 Usage no rtcheck G Description Declares that the assertion in which this comp property appears must not
228. t provided by backend 3 148 fmt html Cenplate ess 143 ft dx env T s AS e RENS 152 fut TE EEN 152 fmt inf dir entry 3 c eg dera a da ue Di 113 G get autodoc opte sells 113 get cache dir 2 3i IRR EINER 148 get command option l ooo 132 Get dng as slate oul sex ve pp aeos 120 get docifield 3c x yl e p PRSE d 120 getdoc field dict Sict eves AR as 120 get_first_loc_for_pred 3 121 getlidxbase 3 iio eis AER hells 151 get idrsub 2 ege deed LTEM HS VR 151 getomaiimod L unen ati tea nes 129 Set maimod specil esses 130 get mod doc 3 udo et Ug iot 120 Set Output LE Ree bep ees 148 get subbase 3 s s ce erre 149 H A REV 133 I idx g t indices 3 v wore be EEUU 152 A he deer EE 143 index comment 2 ees 112 infodir base 2 Roe eese ien 137 insert show Loc cece 127 DD P 102 is andex cmd 1 REENEN 152 is nonempty doctree 1 sss sss 124 is version Li ici ia dech See ee 126 The Ipdoc Documentation Generator L labgen clean Lia A UE 118 labgen get 2 end eles id e MR E AE 118 I bg ipit Listado Di dee Peeters 118 load vpaths 0 ictu ik Exc aa eb pr 132 locate and convert image 4 161 Ipdoc option Les se sing pede e te bes 131 M main_absfile_for_subtarget 3 149 main absfile in format 148 main output name 2 seen 149 pakeinfo i cci 5M A 133 n kertf l uw NER OR ERU Wed ge a 133 mytype l
229. t call time L is currently ground it contains no variables T is currently ground it contains no variables then the following properties hold globally list L T is evaluable at compile time list X T The following properties hold upon exit X is a list Usage list L T Description L is a list of Ts 101 var 1 var 1 list 1 int 1 int 1 list 1 not_fails 1 list 1 int 1 list 1 not_fails 1 not_fails 1 REGTYPE sideff 2 ground 1 ground 1 eval 1 list 1 102 The Ipdoc Documentation Generator og 2 MODE Usage og A T Description This is a parametric mode definition Call and exit are compatible with call T A undefined property The following properties are added upon exit A is ground gnd 1 is 2 PREDICATE Usage Num is Expr Description Typical way to describe document an external predicate e g written in C The following properties should hold at call time Expr is an arithmetic expression arithexpression 1 The following properties hold upon exit Num is a number num 1 Chapter 12 Run time checking of assertions 103 12 Run time checking of assertions Author s Edison Mera This package provides a complete implementation of run time checks of predicate assertions The program is instrumented to check such assertions at run time and in case a property does not hold the error is
230. t ip fee 11 comp assertion 55er vele EM 45 compi oou epa it get ones 42 45 55 COMPILA y o MTM Reb 42 45 conipat 2 oboe MuPHEPPD ae ap PERS 61 72 compatibility properties sss 97 compatible acia io 51 compiler c itf 61 eet eee E 112 115 Compiler iconpiler 112 115 complex argument property 51 52 53 54 55 complex goal poropertg sss se 52 54 55 complex arg property 1 51 52 54 55 complex goal property 1 51 52 53 55 component Tiles land 4 component registry component registry 143 147 compute refs and biblio 1 153 constant 1iz het geet EE dE a Pa ETA 61 66 constraint 1 1 bes 000 Ape UPS pe Ed 77 78 contents area co ies LIE at SE 18 conversion formats ele 3 convertc 1 io bb STRIP Bowel ERG 131 133 COpyrightu i ue Ze a E ved M E PRU LA 34 COEL Li A n PII eia 77 78 GE 77 78 ER A iW A E 18 20 21 107 D Daniel Cabeza mbar em LS 61 The Ipdoc Documentation Generator data facts 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 date icone IX Tq Rh HIR aa ERE Tr eS 29 debugger support 25 42 51 61 77 87 95 104 106 112 115 123 129 131 137 139 141 143 145 147 151 153 155 157 159 161 deci assertions P AI ELA A 47 decl 1 20222 EE 42 47 51 d cl 2 5 2 A RR e Res 42 4T deprecated 1 sb ents bes ed E dese EE 61 73 description list
231. ted in documentation in the interface description by type user system engine Supports new hide option in comments to prevent an exported predicate from being documented This is useful for example for avoiding mentioning in the docu mentation multifile predicates which are not intended to be modified by the user Manuel Hermenegildo 12 The Ipdoc Documentation Generator Version 1 3 1998 7 10 16 35 2 MET DST Exports are now listed in the chapter header separated by kind pred types prop erties The list of other modules used by a module is now separated in the chapter header into User and System modules controlled by two sets of paths in SETTINGS New hide option of comment 2 decl prevents an exported predicate from being included in the documentation comment hide p 3 Manuel Hermenegildo Version 1 2 1998 6 4 9 12 19 MET DST Major overall improvements Manuel Hermenegildo Version 1 1 1998 3 31 Incorporated autodoc and autodoformats library to source in order to make distri bution standalone Improvements to installation and documentation Makefiles now also install documentation in public areas and produce global indices Several documents can cohexist in the same installation directory Manuel Hermenegildo Version 1 0 1998 2 24 First Ciao native distribution with installation Manuel Hermenegildo Version 0 9 1998 2 24 Intermediate version preparing for first major release
232. tegers we will call this property compatible with intlist 1 For example instantiated to intlist 1 should be true for the terms and 1 2 but should not for X 34 2 and X 2 In turn compatible with intlist 1 should be true for X 1 2 and X 2 but should not be for XI 11 a 2 and 1 We refer to properties such as instantiated to intlist 1 above as instantiation properties and to those such as compatible with intlist 1 as compatibility properties corresponding to the traditional notions of instantiation types and compatibility types It turns out that both of these notions are quite useful in practice In the example above we probably would like to use compatible with intlist 1 to state that on success of string concat 3 all three argument must be compatible with lists of integers in an assertion like success string concat A B C gt compatible with intlist A compatible with intlist B compatible with intlist C With this assertion no error will be flagged for a call to string concat 3 such as string concat 20 L R which on success produces the resulting atom string concat 20 L 20 L but a call string concat a R would indeed flag an error On the other hand and assuming that we are running on a Prolog system we would probably like to use instantiated to intlist 1 for sumlist 2 as follows 58 The Ipdoc Documentation Generator calls sumlist L N instantiated to intlist L
233. th L N N gt 100 Now a series of assertions This declares the entry mode of this exported predicate i e how it is called from outside entry p 3 gnd var var This describes all the calls calls p 3 foo bar baz foo _ hh hh d This describes the successes for a given type of calls success p 3 int int var gt int int gnd This describes a global property for a given type of calls comp p 3 int int var not fails doc p 3 A bf general comment on the predicate Documenting some typical usages of the predicate pred p 3 int int var int int list iso not fails This mode is nice pred p Preds Value Assoc var var list int int list not fails This mode is also nice pred p 3 list int list not fails not fails Just playing around pred q A list A list A gnd A not fails Foo pred q A Not a bad use at all 92 The Ipdoc Documentation Generator pred q 2 var gnd int gt gnd int int pred q 2 int list Non moded types are best used this way q _ pred p 1 var gt list p _ pred r A list A gt list A int gnd A not_fails This uses parametric types doc doinclude s 1 Forces documentation even if not exported pred s A list A gt list A gnd A not_fails s _ doc doinclude list 2 list 1
234. that will be produced when incorporating this file into a larger document It is also possible to generate more complex documents by editing the automatically provided SETTINGS pl in the same way as when generating a manual from the command line see below However when generating complex documents it is best to devote an independent permanent directory to the manual and the full procedure described in the rest of this text is preferred 2 2 Generating a manual Two possible scenarios are described in this section The first one is indicated to document quickly a single module and the second one targets the documentation of a larger application or library in which the settings which define how the documentation is to be generated etc are read from a file so that they can be reused as the application library evolves In order to make 1pdoc generate quickly the documentation of a single file it suffices to execute the command 1pdoc d doc structure modulename dvi where modulename is the module to be documented without extension and in this example dvi is the desired format of the manual other accepted formats include html pfd ps etc see later lpdoc will generate a manual with the name of the module and the format extension in the example it would be modulename dvi in the same directory where it is executed For the second scenario the lpdoc library directory includes a generic file which is quite useful for the genera
235. tion of complete manuals the SETTINGS pl file Use of this file is strongly recommended Generating a manual using this file involves the following steps e Create a directory e g doc in which the documentation will be built The creation of this directory is recommended as it will be populated with intermediate files which are best kept separate This directory is typically created in the top directory of the distribution of the application or library to be documented e Execute the command lpdoc lpsettings in the directory where the documentation is to be created e g doc in the previous point lpdoc will create an SETTINGS pl generated file with the default settings This file should be renamed to SETTINGS pl once the user agrees with its contents e Edit SETTINGS pl to suit your needs It is recommended that you review at least the following points 16 The Ipdoc Documentation Generator Set the variable filepath to include all the directories where the files to be documented can be found Set the variable systempath to include all the system directories where system files used can be found regardless whether they are to be documented or not This will be used to access definitions of types etc It is very important to include all related directories either in filepath or in systempath because on startup lpdoc has mo default search paths for files defined not even those typically defined by default in the Prolog system unde
236. tor yf Postfix associative the subexpression can be of the same precedence as the operator General properties operator specifier X The following properties hold globally operator specifier X is side effect free sideff 2 operator specifier X If the following properties hold at call time X is currently a term which is not a free variable nonvar 1 then the following properties hold globally operator specifier X is evaluable at compile time eval 1 All calls of the form operator_specifier X are deterministic is_det 1 Goal operator_specifier X produces 7 solutions relations 2 operator_specifier T The following properties hold upon exit T specifies the type and associativity of an operator operator specifier 1 Usage operator specifier X Description X specifies the type and associativity of an operator list 1 REGTYPE A list is formed with successive applications of the functor 2 and its end is the atom Defined as The Ipdoc Documentation Generator listC list 1 L list L General properties list L The following properties hold globally list L is side effect free list L If the following properties hold at call time L is currently ground it contains no variables then the following properties hold globally list L is evaluable at compile time All calls of the form list L are deterministic list T The following propertie
237. tree R Description Not empty test The following properties should hold at call time Intermediate tree representation for documentation empty doctree 1 Usage empty doctree R Description Empty The following properties should hold at call time Intermediate tree representation for documentation doctree insert end 3 Usage doctree insert end AO Elem A Description Insert Elem in AO at the end obtaining A Call and exit should be compatible with Intermediate tree representation for documentation Intermediate tree representation for documentation Intermediate tree representation for documentation doctree insert before section 3 Usage doctree insert before section AO Elem A Description Insert Elem in AO before the first section obtaining A Call and exit should be compatible with Intermediate tree representation for documentation Intermediate tree representation for documentation Intermediate tree representation for documentation doctree_concat 3 No further documentation available for this predicate REGTYPE PREDICATE doctree 1 PREDICATE doctree 1 PREDICATE doctree 1 PREDICATE doctree 1 doctree 1 doctree 1 PREDICATE doctree 1 doctree 1 doctree 1 PREDICATE Chapter 17 Documentation Abstract Syntax Tree 125 doclink 1 REGTYPE Usage Description A link to a document label doclabel 1 REGTYPE Usage D
238. ty conjunction 1 50 The Ipdoc Documentation Generator Chapter 5 Types and properties related to assertions 51 5 Types and properties related to assertions Author s Manuel Hermenegildo This module is part of the assertions library It provides the formal definition of the syntax of several forms of assertions and describes their meaning It does so by defining types and properties related to the assertions themselves The text describes for example the overall fields which are admissible in the bodies of assertions where properties can be used inside these bodies how to combine properties for a given predicate argument e g conjunctions etc and provides some examples 5 1 Usage and interface assertions props S e Library usage use_module library assertions_props e Exports Properties head_pattern 1 nabody 1 docstring 1 Regular Types assrt_body 1 complex_arg_property 1 property_conjunction 1 property_ starterm 1 complex_goal_property 1 dictionary 1 c_assrt_body 1 s_assrt_ body 1 g_assrt_body 1 assrt_status 1 assrt_type 1 predfunctor 1 propfunctor 1 e Other modules used Internal engine modules term_basic arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term compare term typing hiord rt debugger support 5 2 Documentation on exports assertions props
239. uL vp EREPALRORSEES bee 98 Reech cute ne edet e Ee Eege nut 97 Ree ane cord E d d oe re Page ete d 100 Dl Die cosi ade a eaten ee tl tec trad 97 Parse SEET Ne wy MEHN AN 129 pdfview l ugue ds 132 prepare current refs l sss 153 prepare mathjax 0 sees eese ees 141 prepare web skel t sees 141 PSP Zaire eee EE ug RR Ped 133 psview dl u cote eke a ub Ries qoa 132 Q q 1 voee Seats AS 99 Uli A a AA 96 DAA AS E ENE A 96 read A Y AA A O dcop Palins tae 159 requested_file_formats l 132 reset output dir db 0 esses 112 resolve bibliograpbu s 157 Predicate Method Index S Tc cross d A ette ah 98 se ction prop 2 s d X AE HD DeC 125 section select Drop eee e eee 125 secttree resolve i cele 154 setting valiie 2 2 acc v xe a Ese 132 setting value or default 2 131 setting value or default 3 132 MS AA id do et Uie 159 standalone docstr 1 sees 129 supported file format 1 148 T t buives ate Pe s tu ee RE 98 tex doosI5 VENE ee ee a oh bee ee he ERA 133 texindex Terere i ocd AAA 133 top suttix 2 EE 117 CEO DEE 49 E SE Ve een Yan Shee toe A teste Ld 48 typeindex 5 inel wee ee bat 151 169 UA duco EE oh esr Rie tudo E 97 using math ax ee e ol oes 141 verify settings 000 131 version date cen 127 version numstr 2 eee eee 127 version patch 2 aa ced mise RR Yd Ebene 127 version string 2
240. uld hold at call time AssertionStatus is an acceptable status for an assertion assrt status 1 AssertionBody is a call assertion body c assrt body 1 calls 1 DECLARATION This assertion is similar to a pred 1 assertion but it only provides information about the calls to a predicate If one or several calls assertions are given they are understood to describe all possible calls to the predicate For example the following assertion describes all possible calls to predicate is 2 see arithmetic calls is term arithexpression Usage calls AssertionBody The following properties should hold at call time AssertionBody is a call assertion body c_assrt_body 1 44 The Ipdoc Documentation Generator calls 2 DECLARATION This assertion is similar to a calls 1 assertion but it is explicitely qualified with an assertion status Non qualified calls 1 assertions are assumed to have check status Usage AssertionStatus calls AssertionBody The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is a call assertion body c assrt body 1 success 1 DECLARATION This assertion is similar to a pred 1 assertion but it only provides information about the answers to a predicate The described answers might be conditioned to a particular way of calling the predicate For example the following assertion specifies the answers of the l
241. us regtype AssertionBody The following properties should hold at call time AssertionStatus is an acceptable status for an assertion assrt_status 1 AssertionBody is an assertion body assrt_body 1 Chapter 7 Basic data types and properties 61 7 Basic data types and properties Author s Daniel Cabeza Manuel Hermenegildo This library contains the set of basic properties used by the builtin predicates and which constitute the basic data types and properties of the language They can be used both as type testing builtins within programs by calling them explicitly and as properties in assertions 7 1 Usage and interface basic props Va e Library usage These predicates are builtin in Ciao so nothing special has to be done to use them e Exports e Other modules used Properties member 2 compat 2 inst 2 iso 1 deprecated 1 not_further_inst 2 sideff 2 regtype 1 native 1 native 2 no rtcheck 1 eval 1 equiv 2 bind_ins 1 error free 1 memo 1 filter 2 pe type 1 Regular Types term 1 int 1 nnegint 1 flt 1 num 1 atm 1 struct 1 gnd 1 gndstr 1 constant 1 callable 1 operator specifier 1 list 1 list 2 nlist 2 sequence 2 sequence or list 2 character code 1 string 1 num code 1 predname 1 atm or atm list 1 flag values 1 System library modules assertions native props terms check Internal engine modules term basic arithmetic atomic basic attributes basiccontrol data
242. usa 131 setting value or default 3 pred seususrusruua 132 setting value 2 predi actes kPa oem er S 132 all setting values 2 pred 2 eren eR 132 get command option 1 pred corrida 132 requested file formats 1 red 132 load vpaths 0 pred eiis dian da etna e bi t AC 132 viewer 3 EE 132 ad EE 132 xdvisize 1 pred oscuros toe uuo EE 132 o o AAA verona E kai en 132 psview Fl pred coser eret ES fn 132 htmlview 1 pred s opui hag tete de uM ib et 133 Dibte x Ll EE 133 tex 1 pred esso decies Bey eG ahmed EK Rn 133 texindex T Pred as cava eet Duero eae eee odes 133 dyips l EE 133 ps2pdf NEE RE NO ee ean teeta 133 makeinfo 1 pred eenig ee AE ome 133 makertf 1 EE 244 caved Sigh CEU X MES ARE ERU 133 p ttohllp EE 133 convertc 1 EE 133 LPdoc Backend sissies Sees eee eee ha 135 20 Texinfo Backend cms tas 137 20 1 Usage and interface autodoc texinfo sess 137 20 2 Documentation on exports autodoc_texinfo 137 infodir base 2 pred ag derer sisi eke a 137 20 3 Documentation on multifiles autodoc_texinfo 137 autodoc escape string hook 5 pred 137 autodoc rw command hook 4 pred 137 autodoc finish hook 1 pre 138 autodoc gen alternative hook 2 pred 138 21 22 23 24 25 ITIML Backend ostia 139 21 1 Usage and interface autodoc html sss 139 21 2 Documentation on multifil
243. vailable for this predicate The predicate is of type data docst_gdata_query 2 No further documentation available for this predicate docst gdata query 3 No further documentation available for this predicate docst gdata restore 1 No further documentation available for this predicate docst gdata clean 1 No further documentation available for this predicate 119 PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE 120 The Ipdoc Documentation Generator docst_gvar_save 2 No further documentation available for this predicate docst_gvar_restore 2 No further documentation available for this predicate docst_has_index 2 No further documentation available for this predicate all_indices 2 No further documentation available for this predicate get doc 4 No further documentation available for this predicate get doc field 3 No further documentation available for this predicate get doc field dict 3 No further documentation available for this predicate bind dict varnames 1 Usage bind dict varnames Dict PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE PREDICATE Description Binds the variables in Dict to the corresponding names i e the names that appeared in the source during read get mod doc 3 No further documentation available fo
244. version_maintenance_type 1 REGTYPE Possible kinds of version maintenance for a file version_maintenance_type on version_maintenance_type off version_maintenance_type dir Path atm Path e on version numbering is maintained locally in the file in which the declaration occurs i e an independent version number is kept for this file and the current version is given by the most recent doc version declaration e off no version numbering maintained e dir Path version numbering is maintained globally in directory Path This is useful for maintaining a common global version for an application which involves several files The automatic maintenance of version numbers is typically done by the Ciao emacs mode Usage version maintenance type Type Description Type a type of version maintenance for a file 40 The Ipdoc Documentation Generator Chapter 4 The Ciao assertion package 41 4 The Ciao assertion package Author s Manuel Hermenegildo Francisco Bueno German Puebla The assertions package adds a number of new declaration definitions and new operator definitions which allow including program assertions in user programs Such assertions can be used to describe predicates properties modules applications etc These descriptions can contain formal specifications such as sets of preconditions post conditions or descriptions of computations as well as machine readable textual comments This module
245. y note that the above definition provided that it suits the requirements for being a property and that int 1 is a regular type meets the criteria for being a regular type Thus it could be declared regtype intlist 1 But note that independently of the definition of int 1 the definition above is not the correct instantiation check since it would succeed for a call such as intlist X In fact it is not strictly correct as a compatibility property either because while it would fail or succeed as expected it would perform instantiations e g if called with intlist X it would bind X to In practice it is convenient to provide some run time support to aid in this task The run time support of the Ciao system see Chapter 12 Run time checking of assertions page 103 ensures that the execution of properties is performed in such a way that properties written as above can be used directly as instantiation checks Thus writing Chapter 6 Declaring regular types 59 calls sumlist L N intlist L has the desired effect Also the same properties can often be used as compatibility checks by writing them in the assertions as compat Property basic props compat 1 Thus writing success string concat A B C compat intlist A compat intlist B compat intlist C also has the desired effect As a general rule the properties that can be used directly for checking for compatibility should be downwards close
246. y by using the include command For example the following declaration doc module include Intro lpdoc will include the contents of the file Intro 1pdoc as the module description Alternatively sometimes one may want to generate the documentation from a completely different file Assuming that the original module is m1 pl this can be done by calling the module containing the documentation m1 doc pl This m1 doc p1 file is the one that will be included in the 1pdoc SETTINGS p1 file instead of m1 pl lpdoc recognizes and treats such doc files specially so that the name without the doc part is used in the different parts of the documentation in the same way as if the documentation were placed in file m1 2 8 8 Generating auxiliary files e g READMEs E adas significant parts of this are obsolete They must be updated to describe Ipdoc version Using 1pdoc it is often possible to use a common source for documentation text which should appear in several places For example assume a file INSTALLATION 1pdoc contains text with lpdoc formatting commands describing an application This text can be included in a section of the main file documentation as follows doc module section Installation instructions include INSTALLATION 1lpdoc 24 The Ipdoc Documentation Generator At the same time this text can be used to generate a nicely formatted INSTALLATION file in ascii which can perhaps be included in the t

LPdoc Manual

Contents

Download Pdf Manuals

Related Search

Related Contents