Home

lpdoc Reference Manual - pdf

1. 102 format property T er ees erie hiheti nipti ae 101 format site b gin 4 eirio Ls tese 101 format Siterend L una ib She als els 101 format_usage_header 2 00ooooooccoccoco oooo 100 G generate_description 6 0 89 generate info dir entry 5b 90 generate_man_page 5 0005 89 I Odia RR 66 index comment 2 eee e 94 107 L library directory 4 one RR 91 Dl ria bet EQ IRLO RP Ib ue bb AE 77 option_comment 2 0 cece eee eee eee 95 P p 3 cus d ave ct e de n PD E ole tede 79 PS A PECES 78 a VREET E EE A So A EA tuo E deer Lo 76 WELL AA ont to A ote 76 R O SO TT rewrite command 4 eee 103 rewrite_docstring 4 ooooococccccccooooo 90 SL a a 80 supported_format_suffix 2 94 T tia id 77 o ge Pd see Dd Rus 43 Tr st 4d 4 A ens RM 43 U uL d c sped A euin ts 78 V verbatimize string 3 sess 103 W L dace am E AS CAR Ee ie ed ied o er e 78 108 The Ipdoc Documentation Generator Property Definition Index Property Definition Index CAT AA 67 COMPA Lira RA sut 56 coyered 1 2 2 a DRILL E eO LIWA 64 D docstring 1 miii ts eee ates 23 50 F falls dux qu bf eth see Lara d Me Rin et sched fon GAA 64 H head p ttern 4 cive ueber ede na 46 I indep 225i e up Rae eae dq MUI PE RU xd 66 Sede M coeno ot te tes od occi oT pnr 64 TSO LAY om Ee Reed wus DE thant ete ete feat eee ese
2. 00 e cece eee eee 49 assrt stabus T TEIDE exes ated ber nad antes 49 asert_type 1 regtype face cem ce ber e e ee 50 predfunctor L Tempe luso ta 50 propfunctor 1 respeta oa 50 docstring 1 DPOD naar rai 50 6 Basic data types and properties 51 6 1 Usage and interface basic_prOpS 0oooocooooccommo 51 6 2 Documentation on exports basic props s s esses 51 term 1 regtype c seu test vein gO m P Db NT ierat v 51 o PC 51 nnegint 1 PERE aos vta bene Dey Ce NoD e edt dx erar 52 a A dits ea 52 Dil ROLY IE i adea eus decre tesoros 52 abl TEDUVDe les ideas 52 o A bursa te Eee RE eL 52 grid rests peace Leni eut red el Phe d 52 coustant 1 tegtype ick steve du e ee ex 53 callable 1 regtype 5 3 oret Dolar dd dede 53 operator specifier 1 regtype ooooooooooo 53 E oboe vcre WI pei ne ibtd 54 list 2 regtype aces weeks eue b be pa E 54 inember 2 DEOBUS etri Re qus Eie tps ERE E ME 54 sequemce 2 regtype occiso dba 54 sequence or list 2 regtype o0ooooooommm 54 character code l regbype ninio A 55 string 1 rere i eniin uie dede A aunt 55 preduame T regty pe init pian tee 55 atm or atm _list 1 regtype cocoa en n 56 Compal 2 prop iat se ias 56 SOLAPAS Pi Peete ee eae els 56 not furtherinst 2 prop 15s dur Pee pet 56 regtype 1 Prop inician pario hr bot n 56 7 Declaring regular types o o o o o 57 7 1 Defini
3. ooo oooooocooooomooo 27 spcae horizontal fill o o o ooooooo oooo 27 special characters 0 0 eee e ee eee ee eee 27 Strong dc Cer geb ea eee ees 27 Subsection vct ida Shs ea et 27 Subtitles ies 30 success assertion l l 39 40 supported documentation formats 88 94 synopsis section of the man page 14 syntax of formatting commands 24 system modules eeeeese leeren 13 T texintiosua Lavoro dt 87 texinto leccion te it PU CDDpUbeeemeepIIS 4 textual comments oia meni TEE E EEEE EERE Peis 23 thesis like sStyle oooooooooommooooooo 15 titler 62862426552 tidad bss 30 True assertion eus n Eee PIS og 43 tru st AsserilOn c6 ep ee ea Id 43 two sided id eso m REY med ome etd 14 typewriter like foMt oooocoooooooocccoooo 27 U Universal Resource Locator oo o o oooo o o 26 URL ed gb la 26 Dg IM CE 25 usage of a command seeeeesss selle 28 usage of the applicati0N 0oo oooooocmooo 14 V verbatim texte wag nie E e i RARE RIA 26 version maintenance mode for packages 33 version number seeseseeeee rr 32 W WWW address 000 arane Ae 26 118 The Ipdoc Documentation Generator Global Index Global Index 119 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
4. Qc commands A URP 28 command A O esis 27 CR A Rete et end fie me RE ee 27 O COMA A HS 27 O COMMAND IA 27 Mi AAA as Chel ad ee IO BE heh 28 Command iia we es LR Pe 27 MA oS ee ea 27 Q command sr ree Sha cda 27 Qaa Command saciar uv ae he aie Bees 28 QAA command sessssse en 28 Qae command tI Ee 28 QAE command ssssse esses 28 apl command 0 0 eee eee II 25 Q COMMANG cree ri Ae WE Va oe ea 28 begin cartouche command 27 begin description command 26 Gbeginfenumerate command 26 begin itemize command 26 begin verbatim command 26 Qbf command divi tada eS 27 bullet command 0 0 c cece eee eee 28 Qc command ssa aed We eee ad Be RS 28 cindex command 00 cee cece e e 24 Qcite commands teisei ore eer cece eee eens 25 comment command sees 26 concept command sssseee esee 24 Gcopyright command 0 0 28 Qd command ve lli as Se ees 28 decl command 0 cee cece eee ees 25 Qem command cee eee cece eee aes 27 Qemail command s rosi erninum cece cece ee nes 26 end cartouche command 0004 27 end description command 26 endfenumerate command 2 26 end itemize command 00 00 ee 26 end verbatim command 05 26 Gfl
5. comment version 0 1 1 2001 1 1 A documentation odyssey Control version comment prompting for the file Local Variables mode CIAO update version comments on End 74 The Ipdoc Documentation Generator Chapter 11 Auto Documenter Output for the Example Module 75 11 Auto Documenter Output for the Example Module Author s Alan Robinson David H D Warren Version 0 1423 2001 1 2 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 automatic documentation system 11 1 Usage and interface example_module e Library usage use_module library example module e Exports Predicates q 1 q 2 r 1 t 5 u 3 w 1 p 5 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 Application modules bar Files of module user foo System library modules assertions native_props engine basic_props Internal engine modules hiord_rt arithmetic atomic_basic attributes basic_props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing 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
6. 0 00 cece ee leen 87 N new item in description list 26 O one sided printing sessiles 14 P page numbering changing 14 page size changing eee eee ee eee 14 page style changing o ooooccooooccmmoo 14 paragraph break 0 cee cece eee 27 parametric property 00 eee eee eee 68 parametric regular type abstractions 68 parametric type functor 0000 60 parts in a large document 20 parts in large documents 000 34 planned improvement s lesse eeeeses 32 pred assertion lesse eese 38 39 Prolog 180 Bene eed UR Dep ER cu nd 13 prop assertion lessen 40 41 properties of computati0OS oooo oooooo oo o 5T properties of execution states oo o o o 57 properties basic pressas sni Sieun ER ad 51 properties native oooooocccoccoororooo 63 property abstraction lesse 68 R references 2 uet epu aei deed EO e 25 regiype assertion zc rne ect 60 61 regular type expression isssse esses 60 117 S SeCtlOD eoo ei pha bathe hee SH PIS 27 o Lope were eee eR EP die e ie 25 SETTINGO L Lou n deeper ebur 13 sharing pieces of texXb o ooooooocccoccccooocoo 28 sharing sets rep tmi ei eu e UH os 63 soft side effectS ooooooooocoooocmmmom 66 space extra lines
7. lpdoc help Print this help message Chapter 1 Introduction lpdoc MiscOpts 1 lt path1 gt lt pathN gt s lt path1 gt lt pathN gt i i15 iN u path aliases file p start page t paper type main main lt f1 texic gt lt fN texic gt Generate the main texic file for main application file lt file gt and whose component texic files are lt filel texic gt lt fileN texic gt The optional arguments preceded by l are the directory paths where files used via use module 1 by the file being documented main in this case can be found s is similar but putting paths in the s list flags that such paths are system paths They are treated in the same way as library paths The optional arguments preceded by i are the names of the indices which should be generated The special index name all results in all indices being generated u indicates a Prolog file with defi nitions to be loaded lpdoc MiscOpts 1 lt path1 gt lt pathN gt s lt path1 gt lt pathN gt i lt idx1 gt lt idxN gt u path aliases file component lt file pl gt Generate a texic file for module lt file pl gt The optional arguments are as above lpdoc MiscOpts 1 lt path1 gt lt pathN gt s lt path1 gt lt pathN gt u path aliases file htmlindex main Generate part of an html file suitable for includ
8. not covered 1 PROPERTY not covered X There is some call of the form X for which there is not any clause whose test succeeds DLGHO7 Usage not covered X Description Not all of the calls of the form X are covered Chapter 8 Properties which are native to analyzers 65 is_det 1 PROPERTY is_det X All calls of the form X are deterministic i e produce at most one solution or not terminate Usage is_det X Description All calls of the form X are deterministic 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 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 Usage mut exclusive X Description For any call of the form X at most one clause succeeds not mut exclusive 1 PROPERTY not mut exclusive X Not for all calls of the form X at most one clause succeeds I e clauses are not disjoint for some call Usage not mut exclusive X Description Not for all calls of the form X at most one clause succeeds size 1b 2 PROPERTY size lb X Y The minimum size of the terms to which the argument Y is bound to is given by the expression Y Various measures ca
9. gt list A int gnd A not_fails This uses parametric types comment doinclude s 1 Forces documentation even if not exported pred s A list A gt list A gnd A not_fails comment doinclude list 2 1ist 1 Forces local documentation even iff hh not exported modedef og A gt gnd A This is a Gem mode definition the output is ground comment doinclude og 2 modedef og A T er 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 C gnd A not fails This predicate uses Gem modes extensively Some other miscellaneous assertions Check is default assertion status anyway check pred u og check pred u int list mytype int Chapter hh 10 An Example Documenting a Library Module 73 true status is normally compiler output true pred w list mytype comment doinclude is 2 trust pred is Num Expr arithexpression Expr gt num Num Typical way to describe document an external predicate e g written in C comment doinclude p 5 pred p og int in list int A steps lb 1 length A Version information The ciao el emacs mode allows automatic maintenance comment version 0 142 1998 04 15 10 01 024 MET DST This comment includes the time Manuel Hermenegildo comment version 0 1 3 2001 1 2 The next day is more boring
10. nnegint A predname P A atm P nnegint A Usage 2 predname P Description P is a Name Arity structure denoting a predicate name 56 The Ipdoc Documentation Generator predname P A atm P nnegint A predname P A atm P nnegint A atm or atm list 1 REGTYPE Usage 1 atm or atm list T Description T is an atom or a list of atoms Usage 2 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 the 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 Usage 1 compat Term Prop Description Term is compatible with Prop Usage 2 compat Term Prop Description Term is compatible with Prop iso 1 PROPERTY Usage 1 iso G Description Complies with the SO Prolog standard Usage 2 iso G Description Complies with the ISO Prolog standard not further inst 2 PROPERTY Usage 1 not further inst G V Description V is not further instantiated Usage 2 not further inst G V Description V is not further instantiated regtyp
11. Summary is a string a list of character codes string 1 Indices is a list of atoms list 2 StartPage is an integer int 1 PaperType is an atom atm 1 Opts is a list of supported_options list 2 I is the name of a file filename 1 0 is the name of a file filename 1 OS is an open stream stream 1 format_intro 10 PREDICATE format_ intro Format FileType ModuleType Name NDName Summary Version Comment 0S Intro0S j This predicate defines the format of the introduction and some auxiliary information Format is the type of output e g texinfo latex etc FileType is the type of file Chapter 14 Low level documentation format definitions 97 main component etc ModuleType is how the module is used use module etc Name is the module application name NDName is the same but without _doc if applicable Summary is a brief summary of the contents of the manual taken from the appropriate comment 2 declaration if available Version is the version of the first comment 2 entry which specifies a version number which should be the current version Comment is the introductory text for the module taken from the comment 2 declaration if available OS is the output stream to which writes should be made normally points to the output file IntroOS is the output stream for the introduction Usage format intro Format FileType ModuleType Name NDName Summary Version Comment O Intro0S Description F
12. 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 predicate 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 us
13. ooooooocccoooocoooo 17 log of changes ib REI pb nene iE eh eA 32 ova 75 78 lpdoc 1 3 4 6 13 14 15 16 17 18 19 20 21 22 23 25 33 37 42 46 50 69 83 84 LIpdoc chelpz oc nmi eise ao Pa 14 lpdoc library directory sess 13 lpdoclib autodoc ooooooccccccc eee 94 lpdoclib autodocformats sess 88 1lpdoclib comments 004 88 94 M machine readable comments 23 29 pain body oi a Dahle ets 31 Main file el web ee ee es 4 14 Maan Oo it white bees de acne dace Oo nde dae 3 4 mainie eea i eea E E RpeenIcupIMMeRTP 3 4 M kefile cry uos ck din 1 4 13 15 16 83 Maker nt ou 25 Lo CU e ea Mgr etes 84 MA tore itis ac ie sce a hes 17 18 master dndeX e ole at hoe pr bre bMS 4 Member Zion dda ands adu ted Mew Bes ru 51 54 MESSARCS xv b ob eae LIINC RE ES 88 94 neta predicate 1 red rupe EA 16 99 Meta props wee cic hed by a Sees 3 MODS unc ier ask cette ie E Pin GE doe wrested dads 38 46 mode de lui ES ee Eee 38 41 46 mod typey lo a Nee iE 88 90 mod le COMMON Gece ii Sree Gy Se REPETI eae 31 module declaration sese eese 87 mnodule 1 ux LIQUORE SM As E 87 nodule 2 vu ri x e ERR HEN 87 97 123 MSC Lt A A a UE 63 m ltifile vesicle EN IAS 99 nu t exclusive l v Mathai eee 63 65 N no assit body b cs essi tah a 48 49 Nabody lacs east snes ad SNR 45 48 native Props ve wisest ede ks NEC ace ees 3 netscape v
14. 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 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 16 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 19 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
15. 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 comment 2 DECLARATION Usage comment Pred Comment Description This assertion gives 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 lpdoc manual for documentation on comments docstring 1 4 5 Documentation on exports assertions check 1 PREDICATE Usage check PropertyConjunction Description This assertion provides information on a clause program point position 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 undefined Run time checking of assertions page unde fined Chapter 4 The Ciao assertion package 43 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 i
16. This defines the admissible uses of the comment 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 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 C e Library usage It is not necessary to use this library in user programs The recommended procedure in order to make use of the comment 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 lassertions use package assertions e Exports Properties docstring 1 stringcommand 1 Regular Types version descriptor 1 filetype 1 e Other modules used System librar
17. 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 comment 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 example it is more useful to write added support for pred assertions than modifying file so pred case is also handled 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 1943 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 1722 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 20 The Ipdoc Documentation Generator 2 8 3 Documenting Libraries and or A
18. i AL tas OR ees 38 39 predf nctor 1 2 542 20 Ce RP RR Ro 45 50 predname 1 sz cede uos veg 46 51 55 pretty PEINE gk BV AE S bees 88 program assertions cece eee eee 37 POL OS iaa a 3 13 20 83 Prolog source fileS ooocoooocccooorccocoro 3 Prolog C1a0 4 a IL ds 13 prolog flags 23 38 45 51 63 67 75 88 94 prop assertion d 04i SPEO ORE GE ha 40 A1 prop d j 3 o ELIGE de 38 40 41 prop 2 b A 38 41 67 68 A HER E Teie 68 properti s nacio en nca stv te dee TIS 3 properties of computations 97 properties of execution states 57 properties basigi miis sia ewan d 51 properties native eee eee 63 propertyz dee benedi DM EE qu uM atu 40 property abstraction sese 68 property compatibility 56 property conjunction 1 45 46 47 property_starterm l 45 46 47 propf nctor 1 c ene ae 45 50 providing information to the compiler A1 43 DSUOR TE iu ore Let bas te ua bU AT o o piede deas 84 Q q cia cd tut has p MENO Ue bees tees 75 76 O eite 75 76 DP Lea ede aa wale eRe 75 77 Cd red tte Gabe h lud ote tgs ee tn 88 Ireferenc s i cies ee gen sd eau CU Y 25 84 regtype assertion sees eee 60 61 regtype tei ous senate wesc tu t 51 56 60 61 TEST PO Butt uet 60 61 67 68 TOBY POS seis ee phen ele tale ak Sabet eee 3 regular type iii A 60 The Ipdoc
19. 0 Version 0 9 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 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 separated in documentation in the interface description by type user system e
20. 6 Basic data types and properties Author s Daniel Cabeza Manuel Hermenegildo Version 1 74 208 2002 4 23 19 9 14 CEST Version of last change 1 777204 2002 4 22 18 42 18 CEST 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 6 1 Usage and interface basic_props e Library usage These predicates are builtin in Ciao so nothing special has to be done to use them e Exports Properties member 2 compat 2 iso 1 not further inst 2 regtype 1 Regular Types term 1 int 1 nnegint 1 flt 1 num 1 atm 1 struct 1 gnd 1 constant 1 callable 1 operator specifier 1 list 1 list 2 sequence 2 sequence or list 2 character code 1 string 1 predname 1 atm or atm list 1 e Other modules used Internal engine modules arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing y 6 2 Documentation on exports basic_props term 1 REGTYPE The most general type includes all possible terms Usage 1 term X Description X is any term Usage 2 term X Description X is any term int 1 REGTYPE The type of integers The range of integers
21. AssertionBody is a call assertion body c_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 to 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 42 The Ipdoc Documentation Generator 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 dec1 1 assertion but it is explicitely qualified Non qualified decl 1 assertions are assumed the qualifier check Usage decl AssertionStatus AssertionBody
22. BESUCHEN 27 func l dd o ia wa 48 G PLdssrtsbody A b MIR HIER 45 49 generate_description 6 88 89 generate_info_dir_entry 5 88 90 generate_man_page 5 88 89 generating from emacs 0 0eeeee 13 generating manuals 0c eee eueee 13 gnake ci aie peine ie hei M IB AES 83 emake ql o eee ae eS 14 15 17 ena Tronen eee eei e Shae dee 51 52 GNU general public license 1 GNU MaEk8 zie ree ue 83 ground 1 c conceive be CEDE tdi 64 gunzipiaoBenRbB 5RGRIS4 RE id da 83 H hard sid effects8 i c LEA RE MES 66 head pattern iii ii eee 45 46 49 head pattern 45 46 49 A A A ede ots eic out 75 O A A 4 The Ipdoc Documentation Generator I image FILS wets case A E A mS ISI 29 images inserting llle esee 29 images scaling selle esee 29 include files 3o Sek Gee APR ERE 20 34 include l il Yay degere 20 34 including a predicate definition 29 including an iMage oooocccooocccoorccoooo 29 including cod sonis eaei cece ec eee es 28 including files ss md eke IM REA 28 including images saristi braio cece cece 28 including or not authors 00 0 14 including or not bug info 14 including or not changelog 4 14 including or not versions patches 14 indentation avoiding 05 27 depilar lea el N
23. Note that due to limitations of the info format unfortunately only the first reference will appear in online versions of the document PSPS De 15d t edt at o d e ae eae obe 54 AD ust pf ti Me lei trado o Ino dro dis 47 O ewe Sastes oianean noioe Sada 14 25 SPY Ca a e a a RR dee ed 16 Profiles ii ad bo dev 16 fie dono posui tds 38 m D tse db t ue E gu AN 38 QI command qi oi beaux la eque d 28 Q command 4 804 ac Ee tA Bex ee 27 O Command ia is 27 command bli d ek eed he ee IURE 27 0S COMMAND RI 27 07 Command ca A eet ey 28 command no vie eA es Ona ae bs 27 Q Command cti e de ug 27 Q command ena oer enm Shavers 27 Qaa command IA A nea 28 OAA Command oia Q0 eu PRESTA 28 Qae command 2532 0 ep eee stiles Mec eese 28 QAR command s iu DURER MENS DPULUES 28 CApl command 5 255 nDenbesUex s DL ew 25 QOb command 400 IRR AA 28 begin cartouche command 27 begin description command 26 beginfenumerate command sss 26 Obegintitemize command 26 begin verbatim command oooooommmoooo 26 Obf command metia ra ira 27 Obullet COMO ici aa EE 28 Qc Commands six fades e e hia ila ne ee a 28 Qcindex command eco aa Hee ee es 24 Qcite command miii oe eee ehe 14 25 comment command eee eee eee eee 26 concept command cece eee eee eee 24 copyright command 0c eee 28 Qd command i
24. P A atm P nnegint A predname 1 CommentText is a documentation string docstring 1 Usage 11 comment CommentType CommentText Description Documents a known bug or planned improvement in the module or application 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 comment bug Comment text still has to be written by user The following properties should hold upon exit CommentType and bug unify 2 CommentText is a documentation string docstring 1 Usage 12 comment 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 ComnentText 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 comment version 1 1 21 1998 04 18 15 05x 01 EST Added some missing comments Manuel Hermenegildo The
25. basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing y 9 2 Documentation on exports meta_props call 2 PROPERTY 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 68 The Ipdoc Documentation Generator prop 2 PROPERTY Usage prop A 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 regtype A 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 neta 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 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
26. be one less than in the definition of such property All arguments of each such term are ground 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 terms 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 48 The Ipdoc Documentation Generator 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
27. 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 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 file and typing gmake 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 netscape a command gmake htmlview is available which if there is an instance of netscape running in the machine will make that instance visit the manual in html format To make these files publicly readable on the W
28. 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 property conjunction 1 44 The Ipdoc Documentation Generator Chapter 5 Types and properties related to assertions 45 5 Types and properties related to assertions Author s Manuel Hermenegildo Version 1 74 208 2002 4 23 19 9 14 CEST Version of last change 1 7
29. ctr 30 btbree o0f 2 5rd en eet A os 75 76 troubleshooting lesse esee 13 trie assertiom eee he euer we Vn 43 Er iia wu deese 38 43 trust assertioliuriatanlro goce Na RAE 43 E 1 ee Si e EA te eee vee 38 43 ttyout soweit IA a ane NS bee es 88 two sided iyw A is 14 TYPOS ise eee bou esu s E T LL 3 typewriter like font ooooccooooccooooo 27 125 unix cgi xau t md rM t et dm 18 unix nian format 1 23 5 DELI RAS 89 URL anre eere av ec E 26 rlcreferenc s o ll slat Mea hee et 8 MES a a so aoe e ME udis 25 USA ETT ds 38 usage of a command cee cece eee 28 usage of the application 04 14 usage section torpis rania di wage qian n 8 usage CIPS ii aha eee eee 13 usage_message 1 eee cece eee 8 14 Mise modul 1 2 x uev ie Pee 21 use package diiniita 20 34 USID E citations comal wp e ct 14 V A eenand AA athe 47 variable names 200 pole ta lee ee 37 verbatim textual ba pra 26 verbatimize string 3 94 103 version maintenance mode for packages 33 version number este thee eed 32 version descriptor 1 sess 23 29 version maintenance type 1l 33 35 version number 1 eene 35 VOU Cb or m shad Ah Ae i e ee dep Ms 88 W UA te a A A a a hy 75 78 word heljp a eee ee dpi ita dede 18 word help setup el esses eee 18 word help el v02 i15 RAI REPE RR RAM 18 WEIL cnc NIB NA ete 94 WWW
30. deletes all intermediate files and the generated targets but leaves the texic files 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 12 2 Other software packages required page 83 in order to generate the manuals in the target formats during installation e gmake braveclean performs a complete cleanup deleting also the texic files i e it typically leaves only the SETTINGS and Makefile This is is the most compact but requires in order to generate the manuals in the target formats during installation the presence of the tools mentioned above lpdoc and the source files from which the manuals are generated 2 5 Installing a generated manual in a public area Once the manual has been generated in the desired formats the Makefile provided also allows automatic installation in a different area specified by the DOCDIR option in the SETTINGS file This is done by typing gmake 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 gmake install will create the installation directory place the documentation in the desired formats in this directory and produce and pla
31. 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 18 The Ipdoc Documentation Generator automatically an index for all the 1pdoc generated manuals installed in that directory In order for such manuals to appear when typing M x info 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 file to this directory including the infoindex option in DOCFORMATS and typing gmake install This will install the info manual in directory DOCDIR and update the dir file there gmake 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
32. e machine readable comments in the literate programming style The assertions and comments 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 first in texinfo format From the texinfo output printed and on line manuals in several formats dvi ps info html 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 1pdoc 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 currently fully supported only on Linux and other Un x like systems due to the use of Makefiles and other Un x related utilities It is possible to run 1pdoc under Win32 using Cygwin A version which is written entirely in Prolog and will thus run standalone also on Win32 is currently under beta testing This documentation corresponds to version 1 97458 2002 4 19 20 5
33. effect of selecting that option Currently supported options are option comment v Verbose output good for debugging gt option_comment nobugs Do not include information on bugs option comment noauthors Do not include author names option_comment noversion Do not include version information option comment nochangelog Do not include change log option comment nopatches Do not include comments for patches option comment modes Do not translate modes and their arguments except for properties option comment headprops Do not move head properties to body option comment literalprops Do not use text to document properties option comment nopropnames Do not include property names in prop te option comment noundefined Do not signal undefined properties in te option comment nopropsepln Do not put each property in a separate option comment norefs Do not include a References appendix T option comment nobullet Do not generate initial bullet index htmlbullet with htmlindex file Sel only one manual will be installed in DI option comment nosysmods Do not include system modules in list off libraries used option comment noengmods Do not include system engine modules in 1i of libraries used option comment noisoline Do not include textual description that given usage conforms to the ISO standai option comment propmods Include m
34. made normally points to the output file Usage format predicate begin Format Type Pred Indices 0pts 09 Description Each predicate is an item in an itemized list The following properties should hold at call time Format and texinfo unify 2 Type is currently instantiated to an atom atom 1 Pred is a Name Arity structure denoting a predicate name predname P A atm P nnegint A predname 1 Indices is a list of atoms list 2 Opts is a list of supported_options list 2 OS is an open stream stream 1 format_predicate_comment 3 PREDICATE format_predicate_comment Format Comment 0S This predicate defines the format of Comment an introductory text for the predicate taken from the comment 2 declaration if available Format is the type of output e g texinfo latex etc OS is the output stream to which writes should be made normally points to the output file Usage format predicate comment Format Comment 0S Description Predicate comments are output as is in a separate paragraph The following properties should hold at call time Format and texinfo unify 2 Comment is a string a list of character codes string 1 OS is an open stream stream 1 Chapter 14 Low level documentation format definitions 99 format_predicate_end 2 PREDICATE format_predicate_end Format 0S This predicate defines the format of the last part of the documentation for a predicate Format is
35. new options nosysmods and noengmods selectively avoid listing the system or engine libraries used e 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 e 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 e Added noindent and iso commands e Nicer spacing now when printing predicate names which are operators as well as modes etc e heporting 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 e Exported new declarations also documented now for include type files e A module is now documented even if exports nothing at all e Engine modules used now documented even if no other modules used was a reported bug e Fixed indexing of names containing etc for newer versions of texinfo e Tabs in verbatim modes now converted to a number of spaces 8 Not perfect but produces better output than leaving the tabs in e Tex is now run in nonstopmode which means it will typically not stop if there are minor errors but some errors may go unnotic
36. pae VE RA UNE 23 strong face ly nive b E 27 Struct Wht cates ted ke el I ee 51 52 SUDSCCELON iii saa ee eade o e Ren 27 Subtitle A Mae Ol ee eS ba 30 success assertion esee eee 39 40 SUCCESS dio PUE 38 39 40 SUCCESS 2 bite ge atid nee he oe da 38 40 supported documentation formats 88 94 Global Index supported format 1 88 89 94 supported format suffix 2 94 synopsis section of the man page 14 syntax of formatting commands 24 syntax of regular types s sses s 57 SYSTEM Lidia a x E ted beds ethane Reed aoe eae 88 system moduleS 0 c cece cece eese 13 system_info 23 38 45 51 63 67 75 88 94 tb vob SEGA dE SIS We enne 75 77 CATS caso td 83 term Pen cake eh bee ee Me eee ae Das 51 term_basic 23 38 45 51 63 67 75 88 94 term_compare 23 38 45 51 63 67 75 88 94 term typing 23 38 45 51 63 67 75 88 94 UOS sn onu a y Ie eee e deos n e 88 94 A A do Mee ote cete 63 o wn Te Kb nee ODE EM 22 83 84 TEX iode edv dus iva Er tus Ero 7 o A decide che eer pH de ER 83 84 texi2htmnl I O 84 texindex n AIL Vc SEM 84 texinto ire 1 3 4 14 19 22 87 90 Tegin ne me e anu syst so BI PENES e sas and cs 83 84 texinfo tildes A EE ERIS 4 textual comments Tas Due hl 23 thesis like style cero B v tes 15 Gime struct ld TI red dis 35 lA Ip doc um tou m
37. 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 amy 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 Chapter 4 The Ciao assertion package 41 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 7 Declaring regular types page 57 for some considerations applicable to writing properties 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 properties should hold at call time AssertionBody is an assertion body a
38. 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 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 comment 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 36 The Ipdoc Documentation Generator Chapter 4 The Ciao assertion package 37 4 The Ciao assertion package Author s Manuel Hermenegildo Francisco Bueno German Puebla Version 1 74220
39. te led cans 78 Ts b regtype A enirn eni eh ades 78 11 3 Documentation on multifiles example module 79 pd Prodi pr arci eye 79 11 4 Documentation on internals example module 80 S I Pred ir rta ii 80 rat o A A II a 80 og 2 modeden retiran 80 18 2 pred os A A BE Os 81 12 Installing Ipdoc sioe eR TER 83 12 1 Installing the source distribution o 0ooooooooooo 83 12 2 Other software packages required ooooooococooococooo 83 PART II LPdoc Internals Manual 85 13 Documentation generation library 87 13 1 Usage and interface autodoc oe ert Re aes 88 13 2 Documentation on exports autodoc ooooccoocccoccco oo 88 atodos 10 pred ye doces sh tere tabo aca en ad wed 88 generate man page 5 pred ooooooooooomooo 89 generate description 6 pred ooooooooooo 89 generate info dir entry 5 pred usse 90 rewrite docstring 4 pred oooooooooooomom o 90 modtype 1 regtype 5 2 diarias 90 index comment 2 udreexp ooooooooomoomo 91 option comment 2 udreexp oooooooooooomo 91 13 3 Documentation on multifiles autodoc 0oooooooomo o 91 library directory il pred oreet Sen etit tu rd 91 13 4 Version Change Log autodoc cee eee eee ee 91 14 Low level documentation format definitions 93 14 1 Usage and interface autodocformats ss 94 14 2 Documentati
40. the copyright text taken from the appropriate comment 2 declaration Summary is a brief summary of the contents of the manual taken from the appropriate comment 2 declaration Indices is a list of index names the indices to be generated StartPage is the page number of the first page of the manual I and 0 are the names of the input and output files being processed which can be used for example to put a comment in the generated file saying that the file has been generated automatically from these files and therefore should probably not be edited by hand OS is the output stream to which writes should be made normally points to the output file Usage format front matter Format ModuleType MainOrComp Name NDName Version GVers Title Authors Subtitle Description A texinfo main file is generated Name is used as the name of the file Title is used as the title of the document The Version Authors and the Subtitle will go in the title page Copyright goes in the back of the title page The following properties should hold at call time Format and texinfo unify 2 Name is currently instantiated to an atom atom 1 NDName is currently instantiated to an atom atom 1 Version is a complete version descriptor version_descriptor 1 Title is a string a list of character codes string 1 Authors is a list of strings list 2 Subtitle is a list of strings list 2 Copyright is a string a list of character codes string 1
41. 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 Added a new filetype part This allows splitting large documents into parts each of which groups a series of chapters Other new functionality A style sheet can now be specified which allows modifying many characteristics 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 Cindex cindex and concept now work somewhat differently to make them consistent with other indexing commands The old usage index is now called more appropriately global index Cor respondingly 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 Chapter 1 Introduction 7 The table of contents in printed manuals now contains entries for the individual descriptions of predicates 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 optio
42. 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 58 The Ipdoc Documentation Generator 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 calls sumlist L N instantiated to intlist L 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
43. 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 file to this directory and typing gmake install 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 which is also accessible via WWW After setting DOCDIR to this directory in the SETTINGS file and selecting infoindex and htmlindex for the DOCFORMATS variable gmake install gmake 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 Chapter 2 Generating Installing and Accessing Manuals 19 setenv INFOPATH usr local info DOCDIR setenv MANPATH 4 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 va
44. want the lpdoc binaries libraries and documents installed by setting the corresponding variables in SETTINGS e Type gmake install This should create the 1pdoc executable and install it in the BINDIR directory install the lpdoc library in a separate directory in the LIBDIR directory and install the 1pdoc documentation in the DOCDIR directory e In order for the 1pdoc 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 DOTeshrc for csh in the 1pdoc library 12 2 Other software packages required The most basic functionality of 1pdoc generating manuals in texi format short manua 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 e Generating dvi files 1pdoc normally generates texi files actually a number of texic files F
45. will be used as the abstract for the whole manual There should be at most one of these declarations per module Example comment summary This is a bf very important library The following properties should hold upon exit CommentType and summary unify 2 SummaryText is a documentation string docstring 1 Usage 7 comment ComnentType ComnentText 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 subsections if substructure is needed Example comment module This module is the lib comments library The following properties should hold upon exit CommentType and module unify 2 CommentText is a documentation string docstring 1 Usage 8 comment CommentType CommentText Description Provides additional comments text for a module or application When generating documentation automatically the text in CommentText 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 Example comment appendix Other module functionality The following pro
46. 03 rewrite command 4 pred ooooooooocoomoo 103 14 3 Version Change Log autodocformats 104 Relerences veo vex il 105 Predicate Method Definition Index 107 Property Definition Index 109 vi The Ipdoc Documentation Generator Regular Type Definition Index 111 Mode Definition Index 113 Concept Definition Index 115 Global Index zs od px eee esr edd dip es 117 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
47. 1 index_comment 2 UNDOC_REEXPORT Imported from autodocformats see the corresponding documentation for details option_comment 2 UNDOC_REEXPORT Imported from autodocformats see the corresponding documentation for details 13 3 Documentation on multifiles autodoc library directory 1 PREDICATE No further documentation available for this predicate The predicate is multifile The predicate is of type dynamic 13 4 Version Change Log autodoc Version 0 0 1996 10 10 First prototype Manuel Hermenegildo 92 The Ipdoc Documentation Generator Chapter 14 Low level documentation format definitions 93 14 Low level documentation format definitions Author s Manuel Hermenegildo Version 1 94258 2002 4 19 20 59 33 CEST Version of last change 1 94450 2000 4 18 3 22 13 CEST This module defines the interface for the auxiliary predicates needed by the automatic docu mentation generation library these predicates determine the precise format in which the output is written Also this module includes definitions of these predicates for a few formats The main output format supported is texinfo see The GNU Texinfo Documentation System manual for more info from which 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 als
48. 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 XINL 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 integers 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 4 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 X11 3 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
49. 2 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 s A do not fail Usage 1 list L T Description Lis a list of Ts Usage 2 list L T Description Lis a list of Ts 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 PREDICATE list 1 list 1 gnd 1 not_fails 1 REGTYPE Chapter 11 Auto Documenter Output for the Example Module 81 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 The following properties hold upon exit Num is a number arithexpression 1 num 1 82 The Ipdoc Documentation Generator Chapter 12 Installing Ipdoc 83 12 Installing lpdoc Author s Manuel Hermenegildo Version 1 94458 2002 4 19 20 59 33 CEST Version of last change 1 97240 1999 12 9 21 3 59 MET The source distribution contains all the source code and libra
50. 208 2002 4 23 19 9 14 CEST Version of last change 1 5771 1999 11 29 17 12 34 MET This library contains a set of properties which are natively understood by the different pro gram 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 C assertions native props or also as a package use package nativeprops Note the different names of the library and the package e Exports Properties linear 1 mshare 1 fails 1 not fails 1 possibly fails 1 covered 1 not covered 1 is det 1 possibly nondet 1 mut exclusive 1 not mut exclusive 1 size 1b 2 size ub 2 steps 1b 2 steps ub 2 sideff pure 1 sideff soft 1 sideff hard 1 e Other modules used System library modules andprolog andprolog rt terms vars sort lists Internal engine modules arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing y 8 2 Documentation on exports native_props 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 lin
51. 56 L i ear 1 3 ee Sele ke ee Amen te ee eee a 63 Long ia A X eh ad BE Gene 78 M member 2 im net eon a ae eke eet 54 nshare 1 uoi uuu ad 63 109 r tsexclusive 1 ded Lees eae 65 N HAD di a pee eoe 48 not corer d e aena do e eie qui 64 Dot A E i Le A 64 not_further_inst 2 oooooooo o 56 not_mut_exclusive l 65 P possibly f ils 1 oir td 64 possibly nondet 1 esses 65 ptop 2 5 5 d ne ei eben ders 68 proptabs Ie c da ELI E E A P EXE ERR 68 regtype hss i653 pe hae A DUE EEMS 56 regtype 2i en tet pas 68 sideff hard i mz Iihidig cx je bee ae 66 sideff pure 1 A AR MEX EMG 66 sadeff soft d oue pos Me Bend em AES ue em 66 gize lb 2 oer Arn EDDA ev 65 Size b 25V rt nca edet d erc eS 65 Steps 1b 2 G mt get deo head duse 66 Steps ub 2 5 vc p E pu oA OPES 66 stringcommand 1 esee cece eee eee 24 110 The Ipdoc Documentation Generator Regular Type Definition Index Regular Type Definition Index A AOL A da der RARE SERA 76 assrt body i iissose enr vex RE i 45 assrtsstatus l Pde Asien bh tener date ug 49 aSsrt type lo uie LIP UU SECRET 50 atm 1 uo vectus tud Co E nave d do RR 52 atm or atm list 1 eee 56 B bar d uiososaockec a E D id a ER 75 Dari A dd 75 Cass t body Lio 48 callable 1 ai ai TA a 53 character code 1 cc cece eee 55 complex arg property 1 ss sess 46 comp
52. 77156 2001 11 24 13 23 30 CET 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 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 System library modules dcg expansion Internal engine modules arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing v 5 2 Documentation on exports assertions props 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 b
53. 8 2002 4 23 19 9 14 CEST Version of last change 1 5748 1999 12 9 21 1 11 MET 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 be formal specifications such as preconditions and post conditions or machine readable textual comments This module 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 manual level For a more tutorial in
54. 9 33 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 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 12 Installing Ipdoc page 83 Other parts of this document provide e Documentation on the syntax and meaning of the assertions tha
55. CATE PREDICATE Chapter 14 Low level documentation format definitions 101 format_site_begin 4 PREDICATE format_site_begin Format Text Bullet 0S This predicate defines the format of the header of the description of a set of properties for a given site at calls on success global properties etc Format is the type of output e g texinfo latex etc Text describes the site Bullet says if a bullet should precede the text OS is the output stream to which writes should be made normally points to the output file Usage format_site_begin Format Text Bullet 0S Description Each site is an item in an itemized list The following properties should hold at call time Format and texinfo unify 2 Text is a string a list of character codes string 1 Bullet is an atom atm 1 OS is an open stream stream 1 format_site_end 2 PREDICATE format site end Format 089 This predicate defines the format of the end of the description of a set of properties for a given site Format is the type of output e g texinfo latex etc OS is the output stream to which writes should be made normally points to the output file Usage format_site_end Format 0S Description Simply end of item a newline The following properties should hold at call time Format and texinfo unify 2 OS is an open stream stream 1 format_properties_begin 2 PREDICATE format properties begin Format 08 This pre
56. CJPSg uo ear V rv ehe e E der ESS 84 CIGD sons ciu eheu Dae Nel clone She Ls 3 comment ES A 42 ede do Bake oaks NES 26 comment assertion sees eee eee eee 42 comment Strin8 o ooocoocooo oo 46 48 49 Global Index 7 16 20 21 23 29 33 34 38 42 96 comment 2 97 98 COMMON E Sui ta io x est Rr LEX 3 21 comments machine readable 37 COMME Di ii A 9 comp asSertion J c4 x o 40 Conp 1 obj oo Yt 38 40 49 COMP LD he c T E e Er Er 38 40 colipat 2 Id pev S bete Een 51 56 compatibility properties sss 97 CONpatEble lcegeues Lien e Rue Sad 45 compiler c itf 1 3 a ae 88 compiler compiler 0000 88 complex argument property 45 46 48 49 complex goal property 46 47 49 complex_arg_property 1 45 46 48 49 complex_goal_property 1 45 46 47 49 component files 0 ee eae 4 14 COMponent order oui wees eae a due ee 88 components eet eis a eRe Eee sees 88 Constant diia ovate es ae fe ee 51 53 contents areare os et ela ER MES da 16 conversion formats esee 3 CODyright 6 ev Rede eta Be et ee Bayete ee 30 covere d 14 vie Lm dede 63 64 CMA A 16 18 83 D data d cite cr be IE 99 data facts 23 38 45 51 63 67 75 88 94 date dots ei cte er e et RO E TE 2f deg EXPANSION ocios 45 decl0 VO raae ies do da a pd ea e ed 88 decl assertion 3 ee t
57. Description T is a compound term Usage 2 struct T Description T is a compound term Chapter 6 Basic data types and properties 53 gnd 1 REGTYPE The type of all terms without variables Usage 1 gnd T Description T is ground Usage 2 gnd T Description T is ground constant 1 REGTYPE Usage 1 constant T Description T is an atomic term an atom or a number Usage 2 constant T Description T is an atomic term an atom or a number callable 1 REGTYPE Usage 1 callable T Description T is a term which represents a goal i e an atom or a structure Usage 2 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 x
58. Documentation Generator regular type abstractions o o 60 regular type definitions 57 regular type expression o ooo ooocoo 60 regular TIPOS cs v deser ats i aee da Es 57 rewrite_command 4 94 103 rewrite_docstring 4 88 90 r n time Checks e ho Mle eg ook aes 41 SAA AAA 80 A d pes RT 45 48 Tea aa k o1 d S IA xL DM D tae de ees 24 Sectioh e bI do muere REM Ex 27 SOCIOS rs pl IA au decr S REI NES 25 SOQUENCE Deia LS ninia 51 54 sequence or list 2 s s sess 51 54 SETTINGS 4 6 13 14 15 17 18 19 20 21 25 sharing pieces of text eee eee 28 Sharing Sets 0f facet es p dee wae eh ae ao 63 sideff hard 1 4 oi a 63 66 sideff pure 1 5 4 24 eke kata As 63 66 sideff soft 1 cree 63 66 Size lb 2 by ae eise tx TA eins 63 65 size b 2 v Bae a a 63 65 soft side effects iiss cece io eua 66 SOM Brin uo eu ep Meurs ade o EN egt Guede atte atest 63 space extra lines sees ee 27 spcae horizontal fill 27 special characters esee 27 Specifications uti id 37 Steps lb 2 ig x ere eee rx ke 63 66 Steps ub 2 cw nal a uiae 63 66 SULSAMS eo us tiers teed gni abacus dE ERU Gia d us 88 94 streams_basic 23 38 45 51 63 67 75 88 94 SEL GD cei tae A nated R 51 55 stringcommand 1 23 24 42 46 48 49 50 SELENA A
59. E Usage autodoc Format Main LibPaths SysLibPaths Idxs Components PathAliasF StartPage PaperT Description This predicate is the main interface to the automatic documentation library Main is the name of the source file being documented and Components is a list of other files to be documented in relation to this one see below 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 Format the name of the output file also depends on Format The formats supported are given by supported format 1 in library autodocformats If the manual should include other files normally as chapters Components is nonempty and contains the complete names of the component files These files will appear in the manual in the order in which they appear in Components These files can be written manually or generated automatically but must be in a format com patible with Format In particular they can be also generated automatically with this same predicate by simply calling with component as one of the options in Options Chapter 13 Documentation generation library 89 LibPaths is a list of library paths where files used by the module being documented may be found SysLibPaths is similar to LibPaths but provides paths to system libraries PathAliasF is the name of a module containing path aliases Idxs is a list of index names the indices generated autom
60. N Viadeo 88 Contents AA a a mid ni 16 NS oeienlIbe B eReNDO ed mice Mee ee saad 30 date coe ble in ees 27 decl assertion ces ake ee hea Vee as 42 description list vc cig Ske br Boe ek be eed se 26 documentation format 0 cece eee 87 documentation StridgS 0oooooccccccoccooo 29 E emacs Ciao mode cece eee ee eee ee 33 emacs accessing info files 0 17 emacs generating manuals from 13 emacs LPdoc mode 0s eee eee eee 13 email addresses eel De PEERS 26 email addresses oooooocoooccororccromc coo 25 emphasis face fa sea re DR Pp baie eae 2 encapsulated postscript oooocoooccoomoo o o 29 entry assertion ir tes pe URS 41 enumerated list eo mines menat en iena EE e ia 26 ESCAPE SEQUENCES vies rr ek egeo 23 example of Ipdoc use 0 eee eee ee 69 The Ipdoc Documentation Generator F false ASSIM d races eiu sy ees eee 43 fixed format text 0 cee cece eee E NA 26 fixed width font 0 cece cee cee e eens 27 A ee RR EE hts eee 27 formatting commands 23 37 framed Dok evita iia 27 G generating from emacS oooooooocccccccccco 13 generating manuals ooooooocccccccccoo oo 13 H hard side effectS o oooooooonomorormooo 66 html index page 0c eee eee eee 16 I image Mle fos ede ead ee Pee ares BELLE as 29 images inserting sien
61. OSP command roca a vies Ghat eee 27 Oss commando soaua ee io Tae od 28 subsection command o oooocoocococooo o 27 120 Ot command soi dd Ree es RET da e decia 27 OtOdAY COMA ia Ies 27 Ott command secsec ce eL eee an E PIDE 27 Qu command eden ai Ge a i wr eani 27 uref command o 26 Qv COMM AO naaa c b XU EI 27 Qvar command iii dai 25 De A e Ops UE 46 AQ paper tia pde RE LE NE Me 14 abstract n ras rrt ee ene EUH 31 accentssc o tie IRR LM 27 acceptable modesS cece cece eee eee 46 acknowledgements 00 ccc eee e ee eeeee 30 address s c er api ue Le pore 4 neces 26 aggregates Logo dee X a bs PTS 88 94 analyzer output lle nnn 43 andprolog andprolog rt sss 63 Lo x eilrsid RAW EDD DIS 75 76 appendix a E E enum es 31 applicationess set bea ee ee PR 4 arithmetic 23 38 39 45 51 63 67 75 88 94 assertion body syntax 45 48 49 assertions 3 20 21 23 37 38 45 87 assertions assertions_props 38 60 88 94 assertions assrt_lib 88 assertions native props sessss 75 assrt body l lu imet ed b ELEM 38 45 assrt status T ioo xve Atte bp 45 49 assrt type l uy aio 45 50 AM Lio 51 52 atm or atm list 1 cs e ee 51 56 atomic basic 23 38 45 51 63 67 75 88 94 attributes 23 38 45 51 63 67 75 88 94 AU ara Heras Xe 30 author indexing s a E
62. PathAliasF Opts Description Generates a brief description of the application or library in a file This file is intended for inclusion in a larger file that is a catalog of aplications or libraries The file is produced in the format given by Format Main is the name of a the source file which is the main file of the application The name of the output file depends on Format see see supported_format 1 in library autodocformats LibPaths is a list of library paths the module being documented may use SysLibPaths is similar to LibPaths but provides paths to system libraries PathAliasF is the name of a module containing path aliases The following properties should hold at call time Format is a supported typesetting format supported_format 1 90 The Ipdoc Documentation Generator Main is the name of a file filename 1 LibPaths is a list of atms list 2 SysLibPaths is a list of atms list 2 PathAliasF is the name of a file filename 1 Opts is a list of miscopts list 2 generate_info_dir_entry 5 PREDICATE Usage generate info dir entry Main LibPaths SysLibPaths PathAliasF 0pts Description Generates a one line description of the application or library in a file This file is intended for inclusion in a larger file that is a directory of emacs info manu als T he file is produced in ascii Mainis the name of a the source file which is the main file of the application The name of the output file is Main infoi
63. 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 X 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 Incidentally 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 Chapter 7 Declaring regular types 59 as expected it
64. Quref command cece eee eee 26 DN COMO az ot e In EE 27 Qvar command soos ipe is enini aara EEE ne 25 A Ad papere isd e i adds 14 abstracte rory er cas 31 accents assag oia 27 acceptable modes ooooccoocccooocco 46 acknowledgements 0 cece eee como 30 Appendix uci d sale ele ee di E dre E da 31 applicatio uL ree RID UP e EDO etn od 4 assertion body syntax 45 48 49 assertloHs eser kee e cut IDA rue duis 23 At ops c vct ette dete ue teme Pu a 30 automatic documentati0O o ooooooooooo 87 automatic documentation library 8T avoiding indentation sseeeess sees 27 116 B bibliographic citations 00 25 bibliographic entries 0 0 0 cess eee eee 14 bibliographic entry 0 0000000 25 bibtex AAA A ee e 14 25 blank lines ct Yr eee Rr RE Y 27 bold face naa kei un ste ees e a 27 DUS oss A Mate he ESAE RD eti sear 32 calls assertioO o ooooooooooooocmoroomooo 39 check assertion 0 00 c cece eh 42 C180 2 ope dante ne tee As pine De SN EU 13 COMMENE 3 bia 2525 iii 5A add jase ate 26 comment assertion 00 0 e eee eee rnrn 42 comments machine readable 37 COMP assertion cree aegis ee ub iU 40 compatibility properties ooooooooocmomoo 5T component files o ooooooo o 4 14 component order seseeeeeee ee eee eee 88 COMPONE
65. The lpdoc Documentation Generator An Automatic Documentation Generator for C LP Systems The Ciao System Documentation Series Technical Report CLIP 5 97 1 Draft printed on 23 April 2002 Version 1 92258 2002 4 19 20 59 33 CEST Manuel Hermenegildo and the CLIP Group clip dia fi upm es http www clip dia fi upm es The CLIP Group Facultad de Informatica Universidad Polit cnica de Madrid Copyright c 1996 99 Manuel Hermenegildo The CLIP Group 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 addi
66. WW they should be copied into a directory vis ible 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 file to this directory and typing gmake 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 prompt 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 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 file to this directory and typing gmake 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
67. a PiE 66 9 Meta pPropertes esa ERE rr ry a eee eee 67 9 1 Usage and interface meta props oooooooccooccomo 67 9 2 Documentation on exports meta props sese 67 Cally 2 CDEOD ose pba yhoo deci battle Mona bee dg 67 prop 2 DODGE paa 68 r gtype 2 PrOD E A cate 68 9 3 Documentation on multifiles neta props sess 68 callme 2 pred asada dira ci 68 9 4 Documentation on internals meta_propS 0oooo oooo oo 68 Prop abs I ODEODJ acea li oko ar st 68 10 An Example Documenting a Library Module Vueuckaleu ua dd P d aea EAS AAA 69 11 Auto Documenter Output for the Example MO dle ide e rd oe oen rie n de 75 11 1 Usage and interface example module 75 11 2 Documentation on exports example_module 75 bar 1 regtype A A S Ac RU a n 75 IUS NET 45 ar ar A OA 75 aorb 1 regtyDe ri A a 76 A A er vere oo eat var 76 list or aorb 2 regtype Ye exspectes ee aas XR 76 listy d WEBTV pe ennai bud saa Sek Waite Ve ead An ease 8 76 A s com sine det eni E dedit 76 UA pred abest beta outre pts M ose DEM aa 76 rl pred besitos Staa ers vivtes e ea PE prie TT ag T pred dv Et poster t GREECE wkd C EP E Ren TT CIO Pred ceste trtedi utres tor eben ted eta TT 1 8 pred s gin ocd hxc rire tee Cox ceca iet Edad ione 78 WA Pred esas aries a het oe pe ae RN neta e Eas 78 p 5 pr d A Ave eee a iere vise wu ces 78 Ioue T Prop Cos vxo eode St eb
68. above The usual reason for this is that there is no directory path to this file declared in the SETTINGS file 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 file than the maximum number supported by the installed version of tex texinfo installations as mentioned in Section 2 2 Generating a manual page 13 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 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 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 Enhancing Documentation with Machine Readable Comments 23 3 Enhancing Documentation with Machine Readable Comments Author s Manuel Hermenegildo Version 1 94458 2002 4 19 20 59 33 CEST
69. affect the file in which the package is included The following properties should hold upon exit CommentType and version maintenance unify 2 VersionMaintenanceType a type of version maintenance for a file version maintenance type 1 Usage 14 comment CommentType PredName 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 comment doinclude PredName forces documentation for predicate or type property function PredName to be included even if PredName is not exported Also if PredName is reexported from another module a declaration comment doinclude PredName will force the documenation for PredName to ap pear directly in this module Example comment doinclude p 3 The following properties should hold upon exit CommentType and doinclude unify 2 PredName is a Name Arity structure denoting a predicate name predname P A atm P nnegint A predname 1 Usage 15 comment CommentType PredName Description A different usage which allows the second argument of comment doinclude to be a list of predicate names The following properties should hold upon exit CommentType and doinclude unify 2 PredName is a list of prednames list 2 Usage 16 comment CommentType PredName The Ipdoc Documentation Generato
70. ages Thus a comment 2 declaration of this kind strictly only needs to be added to user type files Example comment 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 20 for details The following properties should hold upon exit CommentType and filetype unify 2 FileType describes the intended use of a file filetype 1 Usage 19 comment 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 comment nodoc assertions The following properties should hold upon exit CommentType and nodoc unify 2 FileName is an atom atm 1 Chapter 3 Enhancing Documentation with Machine Readable Comments 35 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 ymd_date 1 REGTYPE A Year Month Day
71. ai 2 8 1 Ensuring Compatibility with All Supported Target FORMS 2 iecit tn E Fue a deed lega rs 2 8 2 Writing comments which document version patch ChAES asnoisan aep e tenes nete detto E etn 2 8 3 Documenting Libraries and or Applications 2 84 Documenting files which are not modules 2 8 5 Splitting large documents into partS 2 8 6 Documenting reexported predicates 2 8 7 2 8 8 Separating the documentation from the source file Generating auxiliary files e g READMEs 2 9 Troubleshootin gets ibunt x p eee eee 3 Enhancing Documentation with Machine Readable Comments 3 1 Usage and interface comments 2 e eee cence ee 3 2 Documentation on exports comments 00 00 eee docsbrine prop td it Dd stringcommand 1 proper ic version descriptor 1l regtype ooooococommmm filetype 1 Tegtype ooooooccccoccccccco rc 3 3 Documentation on internals comments sess comment 2 decl nether eas waa t vice p P en version number 1 regtype ooooooooomoomo ymd date 1 Testy pe ugue tr ete dar plead time struct ls regtype ini in version maintenance type 1 regtype li The Ipdoc Documentation Generator 4 The Ciao assertion package 37 db TIMO coeant areen a A a 37 4 2 Some attention points 0 0 eee tenes 37 4 3 Usage and interface as
72. ally points to the output file format predicates begin 4 PREDICATE format_predicates_begin Format Name Text 0S This predicate defines the format of the first part of the documentation for a set of pred icates Format is the type of output e g texinfo latex etc Name is the module name Text describes which set of predicates is being documented e g exported predicates im ported predicates etc OS is the output stream to which writes should be made normally points to the output file Usage format_predicates_begin Format Name Text 0S Description Predicates will formatted as an itemized list Corresponds to a begin itemize 98 The Ipdoc Documentation Generator The following properties should hold at call time Format and texinfo unify 2 Name is currently instantiated to an atom atom 1 Text is a string a list of character codes string 1 0S is an open stream stream 1 format predicate begin 6 PREDICATE format_predicate_begin Format Type Pred Indices O0pts 0S This predicate defines the format of the first part of the documentation for a predicate the header Format is the type of output e g texinfo latex etc Type is the type of predicate being documented predicate property type etc Pred is the name of the predicate Indices is a list of index names the indices to be generated Opts are the formatting options OS is the output stream to which writes should be
73. ard side effects i e those that might affect program execution e g assert retract indep 1 PREDICATE Usage indep X Description The variables in pairs in X are pairwise independent indep 2 PROPERTY Usage indep X Y Description X and Y do not have variables in common Chapter 9 Meta properties 67 9 Meta properties Author s Francisco Bueno Version 1 77 208 2002 4 23 19 9 14 CEST Version of last change 1 777167 2002 1 3 17 43 50 CET 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 N 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 arithmetic atomic basic attributes basic props
74. art 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 Usage stringcommand C0 Description CO is a structure denoting a command that is admissible in strings inside assertions version descriptor 1 REGTYPE A structure denoting a complete version description 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 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 3 3 Documentation on internals comments comment 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 comment CommentType TitleText 30 The Ipdoc Documentation Generator Description Provides a title for the module library or application Whe
75. as 1 is declared as a mode Acceptable modes are documented in library modes User defined modes are doc umented in modedef 1 Usage head pattern Pr Description Pr is a head pattern 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 field of an assertion l e the following is a valid assertion pred foo X Y nonvar var gt ground X ground Y Usage complex arg property Props Chapter 5 Types and properties related to assertions 47 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 whic
76. atically StartPage is 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 The following properties should hold at call time Format is a supported typesetting format supported format 1 Main is the name of a file filename 1 LibPaths is a list of atms list 2 SysLibPaths is a list of atms list 2 Idxs is a list of atms list 2 Components is a list of filenames list 2 PathAliasF is the name of a file filename 1 StartPage is an integer int 1 PaperType is an atom atm 1 Opts is a list of miscopts list 2 generate_man_page 5 PREDICATE Usage generate_man_page Main LibPaths SysLibPaths PathAliasF Opts Description Generates a brief description of the application or library in unix man format Main is the name of a the source file which is the main file of the appli cation LibPaths is a list of library paths the module being documented may be found SysLibPaths is similar to LibPaths but provides paths to system libraries PathAliasF is the name of a module containing path aliases The following properties should hold at call time Main is the name of a file filename 1 LibPaths is a list of atms list 2 SysLibPaths is a list of atms list 2 PathAliasF is an atom atm 1 Opts is a list of miscopts list 2 generate_description 6 PREDICATE Usage generate_description Format Main LibPaths SysLibPaths
77. ay also be generated Qlibilibname 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 string A reference will be included in the usage index filet filename 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 var varname 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 e 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 inserte
78. baz b 76 aorb 1 A regular type defined as follows aorb a aorb b tree of 2 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 A regular type defined as follows list or aorb T 1 list T 1 list or aorb T 1 aorb 1 list 1 Usage 1 list L Description L is a list Usage 2 list L Description Lis a list q 1 Usage 1 q A Description Foo The Ipdoc Documentation Generator REGTYPE REGTYPE REGTYPE REGTYPE PREDICATE 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 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 gnd 1 not_fails 1 Chapter 11 Auto Documenter Output for the Example Module q 2 The predicate is of type dynamic Usage 1 The following properties should hold at call time Argl is a free variable Arg2 is ground Arg2 is an integer The following properties should hold upon exit Arg1 is ground Argi is an integer Arg2 is an integer Usage 2 Description Non moded types are best used this way Call and exit should be compatible with Argi is an integer Arg2 is a list r 1 The predicate is o
79. 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 This 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 i e 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 16 If the manual is generated from a single main file i e COMPONENTS 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 Th
80. ce 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 point ers to the relevant documents which have been installed The variables HTMLINDEXHEADFILE 16 The Ipdoc Documentation Generator HTMLINDEXTAILFILE and INFODIRHEADFILE j 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 index html and or dir files A variable EXTRAFILES allows defining a list of additional files which will be copied to the DOCDIR installa tion directory This is useful to place figures or other files which the HTML header files use in the installation directory so that paths can be local These files must reside in the directory in which the documentation is being generated 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 automat ically 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 If only one manual is installed selecting the nobullet option for the main file prevents the bullet item from appearing in this contents area Important Note In order for the different compo
81. convenient to build a super structure of parts each of which groups several chapters There is a special value of the second argument of the comment 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 comment filetype part should be inserted in the sequence of files that make up the COMPONENTS variable of the SETTINGS file at each point in which a major part starts The comment title declaration of this file will be used as the part title and the comment module declaration text will be used as the introduction to the part Chapter 2 Generating Installing and Accessing Manuals 21 2 8 6 Documenting reexported predicates Reexported predicates i e predicates which are exported by a module mi 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 comment 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 suffici
82. ctor applied to some of the parametric variables but regular type abstractions might also be used in some cases see Chapter 9 Meta properties page 67 DECLARATION Chapter 7 Declaring regular types 61 A parametric type functor is a regular type defined by a regular program or a basic type Basic types are defined in Chapter 6 Basic data types and properties page 51 The set of 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 regtype AssertionStatus 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 62 The Ipdoc Documentation Generator Chapter 8 Properties which are native to analyzers 63 8 Properties which are native to analyzers Author s Francisco Bueno Manuel Hermenegildo Pedro Lopez Version 1 742
83. cumentation Generator Chapter 13 Documentation generation library 87 13 Documentation generation library Author s Manuel Hermenegildo Version 1 97258 2002 4 19 20 59 33 CEST Version of last change 1 9435 1999 12 9 0 29 7 CET 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 The exact format in which the documentation is generated is defined in an imported mod
84. cumentation 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 e A ground term In this case this term determines a property of the corresponding argument The actual property referred to is that given by the 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 Unless otherwise stated see below the property built this way is understood to hold for both calls and answers For example the head pattern p Input list integer Output is valid and equivalent for example to having the head pattern p Input A Output and stating that the property list A integer holds for the calls and successes of the predicate e Finally it can also be a variable or a ground term 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 list integer Output is valid as long
85. d 0S This predicate defines the format of a predicate descriptor Format is the type of output e g texinfo latex etc HD describes the head of the predicate as a structure whose argunents are the variable names Type is the type of predicate predicate function declaration Standard contains the atom iso is the predicate is iso compliant OS is the output stream to which writes should be made normally points to the output file Usage format head descriptor Format HD Type Standard 0 Description Head descriptors are formatted literally in code format ISO compli ance is formatted using the key command The following properties should hold at call time Format is currently instantiated to an atom atom 1 HD is any term term 1 Type is currently instantiated to an atom atom 1 Standard is currently instantiated to an atom atom 1 OS is an open stream stream 1 format other assrt header 2 PREDICATE format other assrt header Format 0S This predicate defines the format of the header general properties of a predicate Format is the type of output e g texinfo latex etc OS is the output stream to which writes should be made normally points to the output file Usage format_other_assrt_header Format 0S Description Header in bold in separate paragraph The following properties should hold at call time Format and texinfo unify 2 OS is an open stream stream 1 PREDI
86. d 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 26 The Ipdoc Documentation Generator 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 uref URL introduces at point a reference to the Universal Resource Locator i e a WWW address URL uref text URL introduces at point a reference to the Universal Resource Locator URL associated to the text tect emailt address introduces at point a reference to email address address email tert address introduces at point a reference to the email address address associated to the text text 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 text 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 itemi
87. 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 The 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 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 Chapter 5 Types and properties related to assertions 49 e Prisa 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
88. der 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 0 is used instead of 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 admissible commands e Indexing 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 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 text text will be printed in a normal font This command is used to mark that some text i
89. dicate defines the beginning of the description of the properties for a given pred icate Format is the type of output e g texinfo latex etc N is the usage number OS is the output stream to which writes should be made normally points to the output file Usage format properties begin Format 08 Description Properties are formatted as a second level itemized list The following properties should hold at call time Format and texinfo unify 2 OS is an open stream stream 1 format_property 7 PREDICATE format property Format Prop PM DocString VarNames Opts 0S This predicate defines the formatting for a property Format is the type of output e g texinfo latex etc Prop is the actual property a term PM is the module in which the property is defined VarNames is a list of possibly repeated variable names corresponding to the names in the head pattern DocString contains s in the places where the variables names should appear Note that this is suitable for use as arguments for a call to format 2 102 The Ipdoc Documentation Generator OS is the output stream to which writes should be made normally points to the output file Usage format property Format Prop PM DocString VarNames Opts 0S format_properties_end 2 Description Properties are formatted as running text The following properties should hold at call time Format is an atom atm 1 Prop is any term term 1 PM
90. ds to an end itemize The following properties should hold at call time Format and texinfo unify 2 OS is an open stream stream 1 format_multiple_usage_header 3 PREDICATE format_multiple_usage_header Format N 0S This predicate defines the format of the header describing each usage for a predicate with multiple declarations Format is the type of output e g texinfo latex etc N is the usage number OS is the output stream to which writes should be made normally points to the output file Usage format multiple usage header Format N 08 Description Usage header in bold in separate paragraph 100 format usage header 2 format head descriptor 5 The Ipdoc Documentation Generator The following properties should hold at call time Format and texinfo unify 2 N is currently instantiated to an integer integer 1 OS is an open stream stream 1 format_usage_header Format 0S This predicate defines the format of the header describing a single usage for a predicate Format is the type of output e g texinfo latex etc OS is the output stream to which writes should be made normally points to the output file Usage format_usage_header Format 0S Description Usage header in bold in separate paragraph The following properties should hold at call time Format and texinfo unify 2 OS is an open stream stream 1 format_head_descriptor Format HD Type Standar
91. e command vue IIR 25 footnote command 0 eee eee essen 27 QH command AAA AA 27 hfill command 0 0 cece eee eee ee 27 Qr comrmmand a a 28 image conmitand 22xenvzect4e bae rad 29 Qinclude command 0 0 cee ee nnn 28 includedef command 0 0e eee eeee 29 115 includefact command 00 0eeeeee 28 includeverbatim command luus 28 index command 0 cee eee eese 24 Qiso commard 2 205 LR vehere Bk oe 28 item command 0 eee ce e 26 Qj COM dt es steadier ese a eee 28 key command 0 0 eee eee eee eee 27 QI command eleme ete a weeds 28 OL comme ED 28 Olib commandi iv hohe os 25 noindent command sseesesseess 27 Qo commarid ibus Ia ed Re eae 28 QO command 0 ne te e te EH 28 Qoe command 22 xxx ERG MA ae Aa 28 QOE command 0 0 cece cnc een eeee 28 Qop command 1 2 4 3 uo eae ee dees 25 Qp command sare ner aa dEOnlGuee eid 27 pred command 0 esee 24 ref command E aE ee cece ene E 26 result command 0000s cece eee eens 28 section command cece cece eee 27 sp command 0 ee E eee eens 27 Qss command eii KS eee wi See Peek 28 subsection command 0e eee nne 27 Qt command lu 9 Ede ee ee ee is 27 today command 00 eee 27 Qtt command e a ee 27 Qu command 2 2524 da es de Ve MUR NIS 27
92. e 1 PROPERTY Usage 1 regtype G Description Defines a regular type Usage 2 regtype G Description Defines a regular type Chapter 7 Declaring regular types 57 7 Declaring regular types Author s Manuel Hermenegildo Pedro Lopez Francisco Bueno Version 1 742208 2002 4 23 19 9 14 CEST Version of last change 1 549 1999 12 9 21 57 42 MET This library package adds some new declaration definitions and new operator definitions to user programs These new declarations and operators provide some very simple syntactic sugar to support regular type definitions in source code Regular types are just properties which have the additional characteristic of being regular types basic_props regtype 1 For example this library package allows writing regtype tree X 4 X is a tree instead of the more combersome prop 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 The exact syntax of regular types is also described 7 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
93. e 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 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 1pdoc 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 15 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 lpdoc is by setting parameters in a SETTINGS file see Section 2 2 Generating a manual page 13 and 1pdoc will be invoked automatically with the correct options by the Makefile provided with the distribution
94. e in the lib direc tory This command is included in current Linux distributions Generating html files html files are generated directly 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 1pdoc 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 1ib directory of the 1pdoc distribution T hus 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 85 86 The Ipdoc Do
95. ear term mshare 1 PROPERTY 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 64 The Ipdoc Documentation Generator 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 fails 1 PROPERTY fails X Calls of the form X fail Usage fails X Description Calls of the form X fail not fails 1 PROPERTY not fails X Calls of the form X produce at least one solution or not terminate DLGH97 Usage not fails X Description All the calls of the form X do not fail 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 calls Usage possibly fails X Description Non failure is not ensured for calls of the form X covered 1 PROPERTY covered 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
96. ed e The full path of the version maintenance directory is now computed correctly using the directory of the p1 file being documented as base e Notices for missing subtitle copyright and summary now only given from main file and not for components e Added special handling of regtype and generalized it to handle some props specially if there is a certain comp property present Manuel Hermenegildo Version 1 7 1998 12 2 17 43 50 MET Major port to use the ciao 0 8 modular assertion processing library Manuel Hermenegildo Version 1 6 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 Version 1 5 1998 8 23 20 30 32 EST Now supporting a Ccite command YES It automatically accesses the bib entries in bib files using bibtex and produces a References appendix cite can be Chapter 1 Introduction 9 Version 1 4 Version 1 3 Version 1 2 Version 1 1 Version 1
97. ed comment long 1 This is a property describing a list that is longish The definition is Qincludedef long 1 ys 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 length 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 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 comment 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 72 hh hh The lpdoc Documentation Generator Foo pred q A Not a bad use at all pred q 2 var gnd int gt gnd int int pred q 2 int list Non moded types are best used this way pred p 1 var gt list pred r A list A
98. ed 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 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 50 The Ipdoc Documentation Generator assrt_status trust Usage assrt_status X Description X is an acceptable status 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 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 Basic data types and properties 51
99. ee 64 66 indep 2 xus is tarse Ge tee 64 66 index pages out of order o o ooo ooo ooo o o o 16 index comment 2 esses 14 91 94 indices generated automatically 89 info a ucelni 1 4 17 18 19 22 27 83 info path litio iaa cis pat avs 18 inserting iMageS oococooooccocoorcccorcco 8 INSIALL lpdOoC iiz i ale Ra seed 21 installation en cxx pau bul E ER 3 installation of manuals 15 instantiation properties s s 57 int bes hes5ewerm pte etait ame teers 51 integer T i woipenbebl e XR a E AE TE Eds 4T internals manual 3 19 20 Introductions iii eee eee 31 ionak 225 i cet vf eec 23 38 45 51 63 67 75 88 94 io basic 23 38 45 51 63 67 75 88 94 dl uan aid 81 side lr ds ies 63 64 Ol Var ida 8 51 56 italics tacon a da es rS 27 item in an itemized lisSt 26 itemized US iii ai Es 26 K keyboard key AA a EORR QUU ERES 27 Global Index LT io cat ag tye TES ld is 24 letter size paper id eee Ba 15 library s leesx domui DA ume ae dixe ds s 3 library paths iei idete A 89 90 Library modes ii a Eras 46 library directory 1 sssss 88 91 lin at 1 c onec 6se Ea VR S TR ten et uk 63 Linux hex Rene Ree et ore 83 84 List Dia REPE 51 54 56 76 78 Listin a dea 47 51 54 80 list or aorb 2 te tdi 75 76 List es Hilt a MEX 38 40 63 88 94 literate programming
100. ees ee ee ea 42 decline Ie 38 42 45 A A E edP nr ERES 38 42 description list boreu lA n ETE ES 26 dictionaty 1c s lr dd 45 48 dir oii bbb eed SW ENS obs 17 83 docstring 1 23 37 45 46 48 49 50 document_module 2 o ooooooooooo o 103 documentation format ooooooocoooo o 87 documentation strings 0oooooooocooooo o 29 DOT CSHYG oct Sob Rake ee Ode a ee hues A 83 VA PS A A Aa 84 121 dynamic l ue nnb ick awh on Vue 16 99 E enacs i seres 9 13 15 17 18 32 35 83 84 emacs Ciao mode cece eee ees 32 33 emacs accessing info files 17 emacs generating manuals from 13 macs LP doc Mode iin es ences baie ca ade 13 emacs Library eli as 84 enail addressSs ill de ta 26 email addresses 0 0 cece e eee 8 25 emphasis face cui bit sels 6A E ae AROS 27 encapsulated postscript 00000 29 engine basic props esses eee eee 75 ensure_loaded 1 eee eee 7 20 34 entry assertion cta cia de 41 entry xU eps ERES 38 A1 48 enumerated Listes ab eee ER ER qa an 26 environment variableS 83 errhandle sv LE ee ee ebd 88 94 escape sequences esee nn 23 example of lpdoc use cece eee eee eee 69 exceptions 23 38 45 51 63 67 75 88 94 exported predicates sees eee 8T F E E ten ete dau 63 64 false assertion e
101. eese ees 30 AUTOS Marita b a eU Y nur br epe 3 autedoc 10 usse nci ire 88 autodocformats 3 14 87 88 89 91 automatic documentation 87 88 The Ipdoc Documentation Generator DT sies ue uae eme beoe ues eC cade uti nator bare i Hug 75 Bar Wc dus Rid be uae Yeu E ace 75 Bashers sing wage tee eh vd dakar Maia seek tee i 16 basic_props 3 23 38 45 51 63 67 75 88 94 basic props regtype 1 esses eeess 57 basiccontrol 23 38 45 51 60 63 67 75 88 94 Baz denise saad eta ep uum in d E ME ns 75 bibliographic citations 25 bibliographic entries o o oooooccocoooo o 14 bibliographic entry sees eee 25 DIDES esL gk ades Reip es 8 14 25 84 blank INES a EROR 27 bold ade das tres 27 brief description of the application or library e PD DER nep mM 89 DUE xen Tet deu amu s t oma D 32 C c assrt body l evi rtr pads 45 48 elfe lo Gul A mA Ce eeu T T Call Ait inet E 48 CAN Dyas ccd CE 67 callable 1 REED a 51 53 callme 2 exec ire tert oou wee 67 68 calls assertioh o levels eT CAR 39 calls bo ep Dg VPE de IRR SR 38 39 41 calls 24 A ERES 38 39 character String o cros aasin y i E e Aik 37 character code 1 eee 51 55 Check asserti ngsssl o eee ELS IPs 42 check 1 isizik lI dad 38 42 43 A rere ee TLER 3 13 17 18 69 83 Ciao emacs mode sese eee 13 Cla0Cucobe e ti ae bes d 6 7 CLAP Pio a a 63
102. ent to include in the 1pdoc SETTINGS 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 comment 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 simply by using the include command For example the following declaration comment module include Intro lpdoc will include the contents of the file Description lpdoc 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 the 1pdoc SETTINGS 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 Using 1pdoc it is often possible t
103. er eda 43 false l ce UE A RAN Ti 38 43 filenames eii dunes CRX Qi om EET 88 filetype 1i cine b Res a een qe mE 23 29 fixed format texto ness Ade hs Hee ee ae 26 fixed width font e prO PEMEX 27 FLE O A NA ues 51 52 fOO ng A OH aH e jee ape qe 75 footnote eese eie e Ars Rh lo it REA RA 27 formate oeni taa rtr RR KR E Bee 88 94 Format Liria ez 101 format description 3 ss 94 102 format front matter 19 94 95 format head descriptor 5 94 100 format includes and end matter 6 94 102 format intro 10 eis divide iul 94 96 format module usage 14 94 97 122 format_multiple_usage_header 3 94 99 format_native_declaration 3 94 99 format_other_assrt_header 2 94 100 format other info 10 94 102 format predicate begin 6 94 98 format predicate comment 3 94 98 format predicate end 2 94 98 format predicates begin A 94 97 format predicates end 2 94 99 format properties begin 2 94 101 format properties end 2 94 102 format property T sico iR o4 ber pe I 94 101 format_site_begin 4 94 101 format site end 2 eee 94 101 format usage header 2 94 100 formatting commands 3 23 37 framed Doru inerat e rin ep
104. erties should hold at call time Format and texinfo unify 2 Command is a structure denoting a command that is admissible in strings inside asser tions stringcommand 1 Indices is a list of atoms list 2 The following properties should hold upon exit NewCommand is a string a list of character codes string 1 Usage 2 rewrite_command Format Command Indices NewCommand Description Defines the translation between the special commands which can appear in strings inside assertions and html This is still somewhat incomplete The following properties should hold at call time Format and html unify 2 Command is a structure denoting a command that is admissible in strings inside asser tions stringcommand 1 Indices is a list of atoms list 2 The following properties should hold upon exit NewCommand is a string a list of character codes string 1 Usage 3 rewrite_command Format Command Indices NewCommand Description Defines the translation between the special commands which can appear in strings inside assertions and man The following properties should hold at call time Format and man unify 2 Command is a structure denoting a command that is admissible in strings inside asser tions stringcommand 1 Indices is a list of atoms list 2 The following properties should hold upon exit NewCommand is a string a list of character codes string 1 Usage 4 rewrite_command For
105. f Postfix non associative the subexpression must be of lower precedence than the operator yf Postfix associative the subexpression can be of the same precedence as the operator Usage 1 operator specifier X Description X specifies the type and associativity of an operator Usage 2 operator specifier X Description X specifies the type and associativity of an operator 54 The Ipdoc Documentation Generator list 1 REGTYPE A list is formed with successive applications of the functor 2 and its end is the atom Defined as list listC 1 L list L list listC 1 L list L Usage 1 list L Description Lis a list Usage 2 list L Description Lis a list list 2 REGTYPE list L T L is a list and for all its elements T holds Meta predicate with arguments list pred 1 Usage 1 list L T Description L is a list of Ts Usage 2 list L T Description L is a list of Ts member 2 PROPERTY Usage 1 member X L Description X is an element of L Usage 2 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 Usage 1 sequence S T Description S is a sequence of Ts Usage 2 sequence S T Descrip
106. f type data Usage r A Description l his uses parametric types The following properties should hold at call time A is a list The following properties should hold upon exit A is a list of ints A is ground The following properties should hold globally All the calls of the form r A do not fail og 1 No further documentation available for this predicate t 5 Usage t A B C D og E Description This predicate uses modes extensively Call and exit should be compatible with A is a list B is a list C is an integer Q D is an integer og E is a list TT PREDICATE var 1 gnd 1 int 1 gnd 1 int 1 int 1 int 1 list 1 PREDICATE list 1 list 2 gnd 1 not_fails 1 PREDICATE PREDICATE list 1 list 1 aer list 1 78 The Ipdoc Documentation Generator The following properties should hold at call time B is rather long long 1 The following properties should hold upon exit C is ground gnd 1 A is ground gnd 1 The following properties should hold globally All the calls of the form t A B C D og E do not fail not_fails 1 u 3 PREDICATE Usage 2 Call and exit should be compatible with Argl is an integer int 1 Arg2 is a list of mytypes list 2 Arg3 is an integer int 1 w 1 PREDICATE p 5 PREDICATE Usage p og int in list int A The followi
107. following properties should hold upon exit Version is a complete version descriptor version_descriptor 1 CommentText is a documentation string docstring 1 Usage 13 comment CommentType VersionMaintenanceType Description Defines the type of version maintenance that should be performed by the emacs Ciao mode Example Chapter 3 Enhancing Documentation with Machine Readable Comments 33 comment 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 comment 2 declarations in files The version maintenance mode can also be set alternatively by inserting a comment such as 4h Local Variables hh mode CIAO update version comments off hh 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 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
108. formats bf text text will be formatted in bold face or any other strong face em text 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 Ckeytkey 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 orina 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 a 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 Accents and special characters The following commands can be used to insert accents and special characters o gt 0 0 gt 6 o gt o gt o gt 0 o gt 0 o gt 0 u o gt 0 v o gt H o gt e t oo gt 60 28 The Ipdoc Documentation Generator c o gt Q d 0 gt 0 b o gt o oe gt 0e CDE gt E Cae gt en CAE gt E Qaa gt CAA gt o 0 gt Q1 gt 1 QI gt E ss gt 8 gt i Q gt i Qi gt 1 Qj gt Ccopyright gt iso gt bullet gt e result gt gt Inclusion commands The fo
109. h 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 property in the property starterm 1 The idea is that each element of the 2 term corresponds to a 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
110. h are included in the source program and provide the com piler with information regarding characteristics of the program Typical assertions include type 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 requesting it see the documentation for the comment 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 Chapter 2 Generating Installing and Accessing Manuals 17 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
111. he automatically provided SETTINGS 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 The lpdoc library directory includes two generic files which are quite useful for the gener ation of complete manuals the Makefile and SETTINGS files Use of these files is strongly recommended Generating a manual using these files involves the following steps e Create a directory e g doc in which the documentation will be built It is highly rec ommended that this be a separate and initially empty directory This directory is typically created in the top directory of the distribution of the application or library to be docu mented e Copy the file SETTINGS and copy or much better link since you typically will not need to change it the file Makefile from the lpdoc library directory into the doc directory just created The location of the lpdoc library directory is installation dependent see Section 12 1 Installing the source distribution page 83 e Edit SETTINGS to suit your needs It is required that you set the following e Set the variable FILEPATHS to include all the directories where the files to be docu mented can be found e Set the variable SYSTEMPATHS to include all the system directories whe
112. he possible uses of the document after extraction from the 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 1 Introductionis AAA 1 1 Overview of this document 0 0 cece eee ee eens 1 2 lpdoc operation source and target files Tg Ipdocus8pe si el ale RUE Aged Lea L4 Version Change Log lpdoc accio due bene tian deae 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 0 cece eee eee teens 2 3 Working on a manual ssseseseeeeee eee 2 4 Cleaning up the documentation directory 000 2 5 Installing a generated manual in a public area 2 6 Enhancing the documentation being generated 2 7 Accessing on line manuals 0 00 cee e cece eee eens 2 7 1 2 7 2 2 7 3 2 7 4 Accessing html manuals 0 00 ee ee eee Accessing info manuals 0 000 e eee eeeeee Accessing man manuals 000 ee ee eens Putting it all together 0c eee eee ee 2 5 Some sage tips cse pee
113. hold at call time AssertionBody is a predicate assertion body s assrt body 1 success 2 DECLARATION This assertion is similar to a success 1 assertion but it is explicitely qualified Non qualified success 1 assertions are assumed the qualifier check Usage success AssertionStatus 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 comp AssertionStatus AssertionBody The following properties
114. ication 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 declarations instead of ensure loaded 1 and effect since they are included they export operators declarations etc and should typically be documented differently There is a special comment 2 declaration comment filetype which provides a way of defining the intended use of the file T his 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 lpdoc each documented file each component corresponds to a chapter in the generated manual In large documents it is sometimes
115. ien nii ea eee eee ee 29 images SCaling capta Ihe gy 29 including a predicate definition 29 including an image 0000 2 000005 29 including code rocio iria did Ae ead 28 including les yes eV IUE 28 including images 00 54 416s pee ex Rep 28 including or not authors 000 14 including or not bug info 0 14 including or not changelog 14 including or not versions patches 14 indentation avoiding 04 27 index pages out of order 00 0000 16 info path 86 24 adi A tia 18 installations ui uev Rn eR 3 installation of manuals oo o oooooooooo 15 instantiation properties l l eene 5T internals manual sseeeeeeeeeeeeee 19 intFOduGtlon 3e n VE eu 31 italics face osoelcl6I4RREDRRRDBRBIEQBRLUBeBBM MEI 27 item in an itemized liSt 0o oo o oooo 26 itemized list id id o te Veg 26 K keyboard key tn a a aa 27 Concept Definition Index L letter Size paper esee 15 O pu REEL LED eae beets 3 literate programming 005 17 logeofichangess derrito a hee 32 M machine readable comments o ooooo ooo 29 main body s si ae ee Mel sale tele ea ee el 31 main MMO sc oct VRPENTA eH 4 14 Maketile sic 40k sein ao ee ete See pa Oe Ns 13 83 module comment 00 e eee sees 31 module declaration
116. iil x4 ke ds 28 Odecl command meri e Reed 25 Oem Command sieaa s Re Bais Ha Neve 27 email command 0 cee eee eee eee 26 end cartouche command 004 27 end description command 26 end enumerate command 000 26 end itemize command 00 26 end verbatim command 04 26 Ofile command ur fda e IE 25 footnote command 0s eee esee 27 QH command iii dae aba ete ri 27 Oh fi Tl command s uv he ba ee pee AA 27 Qi command A ad het 28 image command 2 cece cece cee 29 include command 0 eee eese 28 includedef command 4 29 includefact command 28 includeverbatim command 28 index command i ce ber ge de ER 24 iso command llt illl at is 28 QOitem command c Me eo ea ud e ead 26 Q3 Conimand cesa ome Pere cres 28 Okey command z up e crt aei 27 QL comadre ota 28 OL comand Ru RP ARMES MER 28 Olib command 1 2252 aa ela 25 noindent command lees leen 27 Qo command raid ao Rig 28 RS AAA O 28 Qoe commons rd ota pn VR 28 GOE Command i5 eee pES OQ uu EM 28 Qop commandc s 22 de bia T BRI MU DIEM 25 Op command ie A a ae 27 Qpred command deg opea 24 Gref command iii xpeizg ue idenxeLbes dex 26 Oresult command il elm seni o Lakes ns 28 section command 2 eee eese 27
117. ing should go in line including indices The following properties should hold at call time Format and texinfo unify 2 Name is the name of a file filename 1 Components is a list of filenames list 2 Indices is a list of atoms list 2 Opts is a list of atoms list 2 OS is an open stream stream 1 verbatimize string 3 PREDICATE Usage Description Escapes needed characters in string as needed for the verbatim command supported natively by the format The following properties should hold at call time Format is a supported typesetting format supported format 1 Arg2 is a string a list of character codes string 1 Arg3 is any term term 1 The following properties should hold upon exit Format is a supported typesetting format supported format 1 Arg2 is a string a list of character codes string 1 Arg3 is a string a list of character codes string 1 rewrite_command 4 PREDICATE rewrite_command Format Command Indices NewCommand Defines the translation between the special commands which can appear in strings inside assertions and the formatting target Indices is a list of index names the indices to be generated Usage 1 rewrite_command Format Command Indices NewCommand 104 The Ipdoc Documentation Generator Description Defines the translation between the special commands which can appear in strings inside assertions and texinfo The following prop
118. ing in an html page lpdoc MiscOpts 1 lt path1 gt lt pathN gt s lt path1 gt lt pathN gt u path aliases file man main Generate a man page lpdoc MiscOpts 1 lt path1 gt lt pathN gt s lt path1 gt lt pathN gt u path aliases file The Ipdoc Documentation Generator infoindex main Generate an info directory entry suitable for including in an info directory 1 4 Version Change Log 1pdoc Version 1 9 1999 7 8 18 19 43 MEST In this release the name of the application has changed to 1pdoc which was found more appropriate since several formats are generated in addition to texi The major changes are listed below New commands begin cartouche and end cartouche commands now supported foonote command now supported New gmake htmlview command makes a running netscape visit the generated html manual Suggested by Per Cederberg New gmake distclean command intended for software distributions Leaves the generated documents and eliminates all intermediate files including texic texi files Adobe pdf format now supported as a valid target Unfortunately embedded eps figures are not supported at this time in pdf output The second argument of comment hide and comment doinclude 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
119. ion 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 property is used 8 The Ipdoc Documentation Generator e 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 e Two
120. ion is needed who did what when etc use an acknowledgements comment Example comment author Alan Robinson The following properties should hold upon exit CommentType and author unify 2 AuthorText is a documentation string docstring 1 Usage 4 comment 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 comment ack Module was written by Alan but others helped The following properties should hold upon exit CommentType and ack unify 2 AckText is a documentation string docstring 1 Usage 5 comment CommentType CopyrightText Description Provides a copyright text This normally appears somewhere towards the beginning of a printed manual There should be at most one of these declarations per module Example comment copyright Copyright c 2001 FSF Chapter 3 Enhancing Documentation with Machine Readable Comments 31 The following properties should hold upon exit CommentType and copyright unify 2 CopyrightText is a documentation string docstring 1 Usage 6 comment CommentType SumnaryText Description Provides a brief global explanation of the application or library The text in SummaryText
121. is 2 2147483616 272147483616 Thus for all practical purposes the range of integers can be considered infinite Usage 1 int T Description T is an integer Usage 2 int T Description T is an integer 52 The Ipdoc Documentation Generator nnegint 1 REGTYPE The type of non negative integers i e natural numbers Usage 1 nnegint T Description T is a non negative integer Usage 2 nnegint T Description T is a non negative integer f1t 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 represented as 1 0e1000 and 1 0e1000 and Not a number which arises as the result of indeterminate operations represented as 0 Nan Usage 1 f1t T Description T is a float Usage 2 f1t T Description T is a float num 1 REGTYPE The type of numbers that is integer or floating point Usage 1 num T Description T is a number Usage 2 nun T Description T is a number atm 1 REGTYPE The type of atoms or non numeric constants The size of atoms is unbound Usage 1 atm T Description T is an atom Usage 2 atm T Description T is an atom struct 1 REGTYPE The type of compound terms or terms with non zeroary functors By now there is a limit of 255 arguments Usage 1 struct T
122. is an atom atm 1 DocString is a string a list of character codes string 1 VarNames is a list of strings list 2 Opts is a list of supported_options list 2 OS is an open stream stream 1 format properties end Format 0 This predicate defines the end of the description of the properties for a given predicate Format is the type of output e g texinfo latex etc N is the usage number OS is the output stream to which writes should be made normally points to the output file Usage format properties end Format 0 format description 3 Description End of the second level itemized list The following properties should hold at call time Format and texinfo unify 2 OS is an open stream stream 1 format description Format Desc 08 This predicate defines the format of Desc an introductory text for the predicate taken from the comment part of a pred 1 declaration if available These coments are generally used to describe a particular usage of the predicate Format is the type of output e g texinfo latex etc OS is the output stream to which writes should be made normally points to the output file Usage format description Format Desc 08 format other info 10 Description The description of the usage is a separate item in the site item list The following properties should hold at call time Format is currently instantiated to an atom atom 1 Desc is a string a list of character code
123. is similar to a pred assertion but it flags that the predicate being documented is also a regular type This allows for example checking whether it is in the class of types supported by the type checking and inference modules Currently types are properties whose definitions are regular programs 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 xisa 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 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 72 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 fun
124. ld hold at call time Argi is an integer Arg2 is an integer Arg3 is a free variable The following properties should hold upon exit Argi is an integer Arg2 is an integer 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 80 The Ipdoc Documentation Generator 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 s 1 Usage s A list
125. lex goal property 1 sees 47 constant 1 suci ENARRARE BAe aa 53 dictionary 1 tota ugue LA taa 48 filetype i1 c2 1636 RR thik Bde aS 29 ETE AA AAA ae VENE Ep US INE tad 52 G gassrt body l i e xDD RR Cee as 49 dd cit c ima quida Pad dare hee era 52 I int d Jj oko rede Noe ed 51 L list 41s21 b t el iM Rie anis 54 76 78 1180 25 A O ON ITESO 54 80 IR a AAA A Sees 76 111 MO EPS diu ia 90 nnegint In E CIE aei 52 n m 1 oeil eoa puto areis 52 operator specifier 1 eeeues 53 predfunctor d ose e mede 50 A pem ete ete VR 55 property conjunction 1 sess 47 property_starterM l ooooococcccccccoco oo 47 proptunctor 1 ves eee o EP 50 S assrt body Iune riadas 48 SEQUCNCE Liceras adele Line p as 54 sequence_or_list 2 0 cece cece S 54 A hie ns Re UBRRHOREPRWDPed e TU 55 Str ct d4 iveoxv dede e ex Ri OES wna es 52 supported format 1 esses eees 94 term ic axes leet lebe RR RIIPERCSRONRR 51 time VStruct ad Ses sev eue A 35 tree of 2ilg wel MP scs P Tue 76 version_descriptor l o oooococoooccoooo 29 version maintenance type 1l 35 version number 1 eene 35 Y yd date Micol ee ae 35 112 The Ipdoc Documentation Generator Mode Definition Index Mode Definition Index O 113 114 The Ipdoc Documentation Generator Concept Definition Index Concept Definition Index bib Aleshia A Eae 14 25
126. library modules aggregates format write streams errhandle operators messages lists terms assertions assertions props Internal engine modules arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing 14 2 Documentation on exports autodocformats supported format 1 REGTYPE Usage supported format Format Description Format is a supported typesetting format supported format suffix 2 PREDICATE Usage supported format suffix Format Suffix Description Format is a format for which formatting code is available Suffix is the suffix that should be used for the generated files The following properties should hold upon exit Format is a supported typesetting format supported format 1 Suffix is currently instantiated to an atom atom 1 Chapter 14 Low level documentation format definitions 95 index comment 2 PREDICATE Usage index comment Index Text Description Type is a type of index which is supported Text describes the index 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 option comment 2 PREDICATE Usage option comment Option Text Description Option is a documentation option which is supported Text describes the
127. llowing 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 former 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 including code examples which may contain s etc 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 Chapter 3 Enhancing Documentation with Machine Readable Comments 29 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 p
128. mat Command Indices NewCommand Description Defines the translation between the special commands which can appear in strings inside assertions and ascii The following properties should hold at call time Format and ascii unify 2 Command is a structure denoting a command that is admissible in strings inside asser tions stringcommand 1 Indices is a list of atoms list 2 The following properties should hold upon exit NewCommand is a string a list of character codes string 1 14 3 Version Change Log autodocformats Version 0 0 1996 10 10 First prototype References 105 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 InformVatica 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 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 opez Garc ia and M Hermenegildo Non Failure Analysis for Logic Programs In 19977 International Conference om Logic Programming pages 48 62 Camb
129. n be used to determine the size of an argument e g list length term size term depth integer value etc DL93 Usage size lb X Y Description Y is a lower bound on the size of argument X size ub 2 PROPERTY size ub X Y The maximum size of the terms to which the argument Y is bound to 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 Usage size ub X Y Description Y is a upper bound on the size of argument X 66 The Ipdoc Documentation Generator 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 Usage steps 1b X Y Description Y is a lower bound on 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 by the expression Y DL93 LGHD96 Usage steps ub X Y Description Y is a upper bound on the cost of any call of the form X sideff pure 1 PROPERTY Usage sideff pure X Description X is pure i e has no side effects sideff soft 1 PROPERTY Usage sideff soft X Description X has soft side effects i e those not affecting program execution e g input output sideff hard 1 PROPERTY Usage sideff hard X Description X has h
130. n 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 comment title Documentation riented Assertions Usage 2 comment ComnentType SubTitleText Description Provides subtitle lines This can be e g an explanation of the applica tion 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 ac cordingly Several of these declarations can appear per module which is useful for e g multiple line addresses Example comment subtitle A Reference Manual The following properties should hold upon exit CommentType and subtitle unify 2 SubTitleText is a documentation string docstring 1 Usage 3 comment 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 declarations per module In order for author indexing to work properly please use one author declaration per author If more explanat
131. n is selected A single texi file is now constructed by grouping the texic files generated 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 target perhaps useful for distributions The generated files now have texic texinfo component Now declarations are always documented as long as there is a decl assertion Also they are now documented in a separate section Bug fixes and other minor improvements The directory containing html manual is now called BASENAME htm1 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 nor malizer problem Fixed problem with no documentation when only modes given Fixed duplication of documentation for internal predicates when also exported Minor formatting problem when no documentation nor definition found for a regtype fixed Determining exports imports etc now done solely by calls to c itf library and thus synchronized with ciaoc compiler Manuel Hermenegildo Version 1 8 1999 3 24 21 15 33 MET This vers
132. ndex LibPaths is a list of library paths the module being documented may use SysLibPaths is similar to LibPaths but provides paths to system libraries PathAliasF is the name of a module containing path aliases The following properties should hold at call time Main is the name of a file filename 1 LibPaths is a list of atms list 2 SysLibPaths is a list of atms list 2 PathAliasF is an atom atm 1 Opts is a list of miscopts list 2 rewrite_docstring 4 PREDICATE Usage rewrite_docstring Format Idxs S RS Description Rewrites a documentation string S into another one RS while processing any embedded commands processing some directly and converting others into the appropriate commands for output format Format Also eliminates any blanks or tabs that appear at the beginning of a line This is needed for example in texinfo although leading blanks are OK for the printed manuals they produce weird info files The following properties should hold at call time Format is a supported typesetting format supported_format 1 Idxs is a list of atms list 2 S is a documentation string docstring 1 The following properties should hold upon exit RS is a documentation string docstring 1 modtype 1 REGTYPE modtype application modtype use_module modtype include modtype part Usage Description Represents the type of file being documented Chapter 13 Documentation generation library 9
133. ndices of a thesis or similar document Does not save trees e Type gmake all you can also type gmake dvi gmake html gmake ps or gmake info to force generation of a particular target 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 gmake dvi The resulting output can be easily viewed by tools such as xdvi which can be started by simply typing gmake view Note that once an xdvi window is started it is not necessary to restart it every time the document is reformatted gmake 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 Several cleanup procedures are provided by the Makefile e gmake clean deletes all intermediate files but leaves the targets i e the ps dvi ascii html etc files as well as all the generated texic files e gmake distclean deletes all intermediate files and the generated texic files leaving only the targets i e the ps 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 gmake realclean
134. nents 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 generated 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 The Makefile also makes provisions for manual deinstallation from the installation area Typing gmake uninstall in a doc directory will deinstall from DOCDIR the manuals correspond ing to the Makefile in that doc directory If a manual is already installed and changes in the number of formats being installed are desired gmake uninstall should be made before chang ing the DOCFORMATS variable and doing gmake 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 whic
135. ng bibliographic entries in bibtex format This is only relevant if you are using citations in the text using the cite command In that case those will be the files in which the citations will be searched for All the references will appear together in a References appendix at the end of the manual If you are not using citations then select the norefs option on the main file which will prevent an empty References appendix from appearing in the manual 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 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 Saves more trees afourlatex This one is a little less compressed than afourpaper smallbook Small pages like in a handbook Chapter 2 Generating Installing and Accessing Manuals 15 letterpaper For printing on American letter size paper afourthesis A thesis like style i e double spaced wide margins etc Useful for inserting 1pdoc output as appe
136. ng properties 0 00 0 cece cece sh 57 7 2 Usage and interface regtypes 0 cece eee eee eee 60 7 3 Documentation on new declarations regtypes 60 regtype 1 decl i orci choice do quo ee ores on 60 Pe by Pe A dal SS ios dadettiee poetas d ed eds 61 8 Properties which are native to analyzers 63 8 1 Usage and interface native props seeseeesese 63 8 2 Documentation on exports native props s s 63 Imearz 1 DPODJ esum ect itecto t rater eee s 63 mshare 1 prop arash esi fetes te eu bw Es 63 A Vio tus aere itas PE RAAKTE EEE e eds 64 not fails 1 ADFOB S Gora dee ho Ce OA Redes epatis 64 possibly falls E prop 5 caer erret hex am rene neet es 64 covered 1 prop A bep d LUN LE E 64 not_covered 1 prop ciere Ea voee E ENG 64 is det I Prop Aesch EE e t x bos ud 64 possibly nondet l DrOp iiec eR 65 mut exclusive 1 prop ses doce nr E ee t 65 not mut exclusive 1 prop reete resa er UP 65 Size ID2 Prop eeu ted es atu edu ex Od 65 size b 2 PrOD arae t Lasst aati hcl ke xo eR sonde 65 steps 1b 2 DIOD uda cente eruere tt 66 steps ub 2 prop ers cita ris See eee eae s ea 66 Side pura prop ta osse ee eite ap orn etas 66 sideff_soft 1 prop stessi rh tee Ee letus 66 iv The Ipdoc Documentation Generator sideff hard 1 prop 2i as eru EE New Xe x 66 mdep 1 Pr d oai on err neta aa ei A ird dett 66 indep 2 Prop A A orici cieie
137. ng properties should hold globally l length A is a lower bound on the cost of any call of the form p og int in list int A steps_1b 2 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 list 1 REGTYPE Usage 1 list L Description L is a list Usage 2 list L Description L is a list Chapter 11 Auto Documenter Output for the Example Module 79 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 shou
138. ngine 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 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 1998 6 4 9 12 19 MET DST Major overall improvements Manuel Hermenegildo 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 1998 2 24 First Ciao native distribution with installation Manuel Hermenegildo 1998 2 24 Intermediate version preparing for first major release Modified Makefile and SETTINGS to handle installation of manuals Manuel Hermenegildo 10 The Ipdoc Documentation Generator Version 0 6 1998 2 10 Added new indices and
139. ns 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 Exports 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 success 1 1150 fx success 2 1150 xfx comp 1 1150 fx comp 2 1150 xfx entry 1 1150 fx New declarations defined pred 1 pred 2 calls 1 calls 2 success 1 success 2 comp 1 comp 2 prop 1 prop 2 entry 1 modedef 1 dec1 1 dec1 2 comment 2 Other modules used ES module assertions include library assertions use package assertions Predicates check 1 trust 1 true 1 false 1 System library modules assertions assertions_props Internal engine modules arithmetic atomic_basic attributes basic_props basiccontrol data_facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing 4 4 Documentation on new declarations assertions 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 ma
140. o 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 94 The Ipdoc Documentation Generator 14 1 Usage and interface autodocformats ay e Library usage use_module library autodocformats e Exports Predicates supported_format_suffix 2 index_comment 2 option_comment 2 format_front_matter 19 format_intro 10 format_module_usage 14 format_ predicates_begin 4 format_predicate_begin 6 format_predicate_comment 3 format_predicate_end 2 format_native_declaration 3 format_predicates_ end 2 format_multiple_usage_header 3 format_usage_header 2 format_head_ descriptor 5 format_other_assrt_header 2 format_site_begin 4 format_site_end 2 format_properties_begin 2 format_ property 7 format_properties_end 2 format_description 3 format_other_ info 10 format_includes_and_end_matter 6 verbatimize_string 3 rewrite_ command 4 Regular Types supported_format 1 e Other modules used Application modules lpdoclib autodoc lpdoclib comments System
141. o 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 program a meta interpreter for this purpose 60 The Ipdoc Documentation Generator 7 2 Usage and interface regtypes j or e Library usage use package regtypes 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 basiccontrol 7 3 Documentation on new declarations regtypes regtype 1 This assertion
142. o use a common source for documentation text which should appear in several places For example assume a file INSTALL 1pdoc contains text with 1pdoc formatting commands describing an application This text can be included in a section of the main file documentation as follows comment module section Installation instructions include INSTALL 1pdoc At the same time this text can be used to generate a nicely formatted INSTALL file in ascii which can perhaps be included in the top level of the source directory of the application To this end an INSTALL pl file as follows can be constructed use package assertions comment title Installation instructions comment module include INSTALL 1pdoc main forces file to be documented as an application Then the ascii INSTALL file can be generated by simply running gmake ascii in a directory with a SETTINGS file where MAIN is set to INSTALL pl 22 The Ipdoc Documentation Generator 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
143. ocu mented Manuel Hermenegildo Version 0 0 1996 10 10 First prototype PART I LPdoc Reference Manual PART I LPdoc Reference Manual 11 12 The Ipdoc Documentation Generator Chapter 2 Generating Installing and Accessing Manuals 13 2 Generating Installing and Accessing Manuals Author s Manuel Hermenegildo Version 1 97258 2002 4 19 20 59 33 CEST Version of last change 1 97457 2002 1 5 0 47 15 CET This part 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 that will be produced when incorporating this file into a larger document It is also possible to generate more complex documents by editing t
144. ocumentation Generator G Puebla F Bueno and M Hermenegildo An Assertion Language for Debugging of Constraint Logic Programs Technical Report CLIP2 97 1 Facultad de InformVatica UPM July 1997 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 Predicate Method Definition Index Predicate Method Definition Index A autodoc IO cee Peed eet ad a nds 88 C callme 2 iuoo gg a peax eae ERR 68 check 1 060502 iene Meee dl ee es 42 F false l cui adi iU Ia aac teg 43 format description 3 sess 102 format front matter 19 csse 95 format head descriptor 5 sss 100 format includes and end matter 6 102 format intro 10 5 ne Eel ee 96 format_module_usage 14 00 97 format_multiple_usage_header 3 99 format native declaration 3 99 format other assrt header 2 100 format_other_info 10 102 format predicate begin 6 98 format predicate comment 3 98 format predicate end 2 sess 98 format predicates begin 4 97 format predicates end 2 99 format properties begin 2 101 format properties end 2
145. odule name to which props belong option comment shorttoc Produce shorter table of contents no entr for individual defs of preds props et option comment regtypeprops Include in the doc for regtypes the gl prop stating that they are indeed regtj option comment onesided For printing on one side default is two 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 96 The Ipdoc Documentation Generator format_front_matter 19 PREDICATE format_front_ matter Format ModuleType Main0rComp Name NDName Version GVers Title Authors Subtitle This predicate defines the first part of the format of the main file of a manual Format is the type of output e g texinfo latex etc different clauses of the predicate can be defined for different formats Name is the name of the application taken from the name of the input file NDName is the same but without _doc if applicable Version is the version of the first comment 2 entry which specifies a version number which should be the current version This is the version of the last local change GVers is the global version Title is the intended title of the application taken from the approriate comment 2 declaration Authors is a possibly empty list of author names Subtitle is a possibly empty list of subtitle e g address explanation lines Copyright is
146. ody 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 to would not make it fail 46 The Ipdoc Documentation Generator 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 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 the assertion hold The usual formatting com mands that are applicable in comment strings can be used see stringcommand 1 See the 1pdoc manual for do
147. on on exports autodocformats 94 supported format 1 regtype ooooooococooo 94 supported format suffix 2 pred issus 94 index comment 2 pred xoci env rex Equum 94 option comment 2 pred o0oooooocoocmcomo 95 format front matter 19 pred 0000 95 format intto 10 pred oui RR eere 96 format module usage 14 pred o o oo 97 format predicates begin A pred 97 format predicate begin 6 pred 000 98 format predicate comment 3 pred 98 format predicate end 2 pred ooooo ooo 98 format native declaration 3 pred 99 format predicates end 2 pred 0 004 99 format multiple usage header 3 pred 99 format usage header 2 pred Less 100 format head descriptor 5 pred sssuse 100 format other assrt header 2 pred 100 format site begin 4 pred oooooooomoomo 101 format site end 2 pred ioi one tr epa os 101 format properties begin 2 pred 101 format_property 7 pred ni ata 101 format properties end 2 pred oooooooooooo 102 format description 3 pred i exse et pepe 102 format other info 10 pred ooooooooomo o 102 format includes and end matter 6 pred 102 verbatimize string 3 pred ooo ooooo o 1
148. 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 directory Manuel Hermenegildo Version 0 1 1997 7 30 First official version major rewrite from several previous prototypes autod
149. ormats intro stuff summary intro etc The following properties should hold at call time Format and texinfo unify 2 FileType is any term term 1 ModuleType is currently instantiated to an atom atom 1 Name is a string a list of character codes string 1 NDName is a string a list of character codes string 1 Summary is a string a list of character codes string 1 Version is a complete version descriptor version_descriptor 1 Comment is a string a list of character codes string 1 OS is an open stream stream 1 Intro0S is an open stream stream 1 format module usage 14 PREDICATE format module usage Format Name Type Exports Mults UMods IUMods SMods EMOds Ops NDec1s NModes Indi This predicate defines the format of the usage info for the module Format is the type of output e g texinfo latex etc Name is the name of the module taken from the module 2 declaration Exports contains the predicates exported by the module taken from the module 2 declaration UMods contains the user modules imported by the mod ule SMods contains the system modules imported by the module EMods contains the internal engine modules imported by the module Ops contains any exported operator definitions NDecls contains any exported new declarations NModes contains any new mode definitions Indices is a list of index names the indices to be generated OS is the output stream to which writes should be made norm
150. particular case of property abstractions 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 69 10 An Example Documenting a Library Module Author s Manuel Hermenegildo Version 1 97258 2002 4 19 20 59 33 CEST Version of last change 1 97239 1999 12 9 21 2 34 MET A simple example of the use of 1pdoc is this manual which can be built in the doc directory of the 1pdoc 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 1pdoc 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
151. perties should hold upon exit CommentType and appendix unify 2 CommentText is a documentation string docstring 1 Usage 9 comment CommentType CommentText 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 comment usage Do not use still in development The following properties should hold upon exit CommentType and usage unify 2 CommentText is a documentation string docstring 1 Usage 10 comment PredName ComnentText 32 The Ipdoc Documentation Generator 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 comment comment 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 predname
152. pplications 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 an application no components A manual of a simple application e Main file is a library 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 appl
153. r 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 comment hide p 3 The following properties should hold upon exit CommentType and hide unify 2 PredName is a Name Arity structure denoting a predicate name predname P A atm P nnegint A predname 1 Usage 17 comment CommentType PredName Description A different usage which allows the second argument of comment hide to be a list of predicate names The following properties should hold upon exit CommentType and hide unify 2 PredName is a list of prednames list 2 Usage 18 comment 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 pack
154. ras ata A andor d Ra Mea barata 1 17 WWW addressing ds essen 26 X XdVi lox Odit Eos auicm Mus 15 126 The Ipdoc Documentation Generator
155. re system files used whether they are to be documented or not can be found It is very important to include all related directories either in FILEPATHS or in SYSTEMPATHS because on startup lpdoc has no default search paths for files defined not even those typically defined by default in the Prolog system under 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 14 For The Ipdoc Documentation Generator Set MAIN to be the name of the main file of the application or library e g main pl header src etc Set COMPONENTS to a possibly empty list separated by spaces of source files These are the component files the rest of the settings in the SETTINGS file you can simply use the default values indicated You may however want to change several of these 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 infor mation 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 autodocformat
156. riables and performing gmake 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 1pdoc 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 results 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 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 Ipdoc 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
157. ridge MA June 1997 MIT Press Cambridge MA S K Debray P LVopez GarcV Nia 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 InformVatica 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 LVopez GarcV Nia 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 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 106 PBH97 PBH98 The Ipdoc D
158. ries 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 Ciao 12 1 Installing the source distribution e Before installing 1pdoc you may want to read Section 12 2 Other software packages re quired page 83 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 edit the file SETTINGS in a text editor 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 difficult and modify the first part of the SETTINGS 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
159. rom the texi files dvi files are generated using the standard tex package di rectly The dvi files can also be generated with the GNU Texinfo package which provides among others the texi2dvi command However Texinfo itself requires the standard tex 84 The Ipdoc Documentation Generator 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 fil
160. s string 1 OS is an open stream stream 1 No further documentation available for this predicate PREDICATE PREDICATE PREDICATE Chapter 14 Low level documentation format definitions format_includes_and_end_matter 6 103 PREDICATE format includes and end matter Format Name Components Indices 0pts 0 This predicate generates code for including the components of a complex document if needed and produces the final matter of the main file Format is the type of output e g texinfo latex etc different clauses of the predicate can be defined for different formats Name is the name of the application taken from the name of the input file If the manual should include other files e g as chapters Components is nonempty and contains the complete names of the component files T hese files will appear in the manual in the order in which they appear in Components These files can be written manually or generated automatically by document module 2 or any other means but must be in a format compatible with Format Indices contains the index names the indices to be generated OS is the output stream to which writes should be made normally points to the output file Usage format includes and end matter Format Name Components Indices 0pts 0 Description The components in Components if any are included as chapters Name is used as the basename of the index component files If no components then everyth
161. s 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 Chapter 3 Enhancing Documentation with Machine Readable Comments 25 in a documentation string A reference will be included in the usage in dex In on line manuals a direct access to the corresponding predicate definition may also be generated Coptoperatornamey 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 m
162. s a variable which appears as a head argument property_conjunction 1 trust 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 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 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
163. s ac inerrant ssepe ides Vier gas 6 17 new item in description list 26 nnegint i i224 Rit Aeentuns Pees eL 51 52 not covered 1 eee 63 64 notwfall 1 ranks E N 63 64 not further inst 1 eese 48 not further inst 2 eee 51 56 not mut exclusive 1 esses 63 65 MUM 1 Ses euro eee D x ux Pide 51 52 O Og lios eua A VERRE ae eae e 77 11 Daria e E ob een 80 one sided printing esses esee 14 Op Bes id Nt adu UE PIU ERE TEE 16 operator specifier 1 sss 51 53 Operators ues re I PRIMO CAD pue Es 94 option comment 2 14 91 94 95 P PLS yb Suus ur th wad RA 75 79 PLD est eat ag oo Sete dee lyk lta Ap EM 75 78 packagesSios ie hate dd te cad E athe 20 34 page numbering changing 14 page size changing esses eese 14 page style changing lisse sese 14 paragraph break cece ce eee 27 parametric property seen 68 parametric regular type abstractions 68 parametric type functor sess 60 parts in a large document 20 parts in large documents s 34 pdftexus d esc ue Ease Tema earner ees 84 perb iiciide ode 4s SUN eau dus 84 124 possibly fails 1 2 in is 63 64 possibly nondet 1 sse sss 63 65 pred assertion serLkerhIIexelderta 38 39 pred l i voe 25 38 39 40 42 45 48 102 pred 2
164. s 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 calls 2 DECLARATION This assertion is similar to a calls 1 assertion but it is explicitely qualified Non qualified calls 1 assertions are assumed the qualifier check Usage calls AssertionStatus 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 length 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 40 The Ipdoc Documentation Generator success length L N list var gt list integer Usage success AssertionBody The following properties should
165. s or type lpdoc help for a list of these options In the same way COMPOPTS sets options for the component files Currently these options are common to all component files but they can be different from MAINOPTS The allowable options are the same as above DOCFORMATS determines the set of formats dvi ps ascii html info manl in which the documentation should be generated by default when typing gmake a11 Se lecting htmlindex and or infoindex requests the generation of parts of a master 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 man1 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 INDICES 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 autodocformats 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 BIBFILES determines a list separated by commas full paths no spaces of bib files i e files containi
166. sertions 0 eee eee 38 4 4 Documentation on new declarations assertions 38 pred ld e e ane opt 38 pred declarada 39 calls Td m 39 calls 2 del ts 39 success 1 dec arios eked e ia 39 success 2 dela dis ld Li 40 compr IL deelyis sixties chien A a 40 A e d 40 prop 1 deel ic er c ewe ag aa 40 prop 2 decl C osce pete Nouv vn So oao EUR wey 41 entry Ide a AER I eb 41 modeder tl dele iia 41 decida aa etae eid datada 42 decl 2 A azn tea bites teks totes atk tlie Meet toned 42 comment 2 decl ise wing tia ote eror daa 42 4 5 Documentation on exports assertions sess 42 cheeky 1 preludio aig ta eae ahead 42 trust T predio di or 43 true D pred vopebe aci or tq d rebates E tvi pestes sd 43 false 1 pred ies TEN TEE EG RE XR YAN ER 43 5 Types and properties related to assertions 45 5 1 Usage and interface assertions props sues 45 5 2 Documentation on exports assertions props 45 assrt body T restype cu pier ds 45 head pattern l prop z icrere ep ac RSEN 46 complex arg property 1l regtype 46 property conjunction 1 regtype o 47 property starterm 1 regtype ooooooooooo 47 complex_goal_property 1 regtype 47 nabody 1 prop PA A E Ep e 48 dictionary 1 CrGebyDe ic as 48 c_assrt body 1 regtype ld ia 48 8 assri Body l regtyDe access oe unns 48 g assrt body 1 regtype
167. ssrt_body 1 prop 2 DECLARATION 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 prop AssertionStatus 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 entry 1 DECLARATION 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 hold at call time
168. t 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 Documentation 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
169. t bug Library is hard to execute no actual code Standard declarations are documented with the corresponding predicate 70 The Ipdoc Documentation Generator data r 1 dynamic q 2 multifile p 3 dynamic p 3 meta predicate p 7 Uncommenting this would make these not appear in the documentation 4 comment 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 hh 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 4 4 tree of void 44 tree of T tree X L R toh X T 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 is itself Chapter hh hh hh 10 An Example Documenting a Library Module 71 is document
170. the type of output e g texinfo latex etc OS is the output stream to which writes should be made normally points to the output file Usage format_predicate_end Format 0S Description Noop each predicate is an item in an itemized list The following properties should hold at call time Format and texinfo unify 2 OS is an open stream stream 1 format_native_declaration 3 PREDICATE Usage format native declaration Format Decl 08 Description This predicate defines the format for documenting miscellaneous decla rations such as meta predicate 1 multifile 1 dynamic 1 data 1 etc Format is the type of output e g texinfo latex etc Decl contains the declaration info 0S is the output stream to which writes should be made normally points to the output file No special comment is generated for the default value static The following properties should hold at call time Format and texinfo unify 2 Decl is any term term 1 OS is an open stream stream 1 format_predicates_end 2 PREDICATE format predicates end Format 08 This predicate defines the format of the last part of the documentation for a set of predi cates Format is the type of output e g texinfo latex etc OS is the output stream to which writes should be made normally points to the output file Usage format predicates end Format 0 Description Predicates will formatted as an itemized list Correspon
171. tion S is a sequence of Ts Chapter 6 Basic data types and properties 55 sequence or list 2 REGTYPE Meta predicate with arguments sequence or list pred 1 Usage 1 sequence or list S T Description S is a sequence or list of Ts Usage 2 sequence or list S T Description S is a sequence or list of Ts character code 1 REGTYPE Usage 1 character code T Description T is an integer which is a character code The following properties hold upon exit T is an integer int 1 Usage 2 character_code T Description T is an integer which is a character code The following properties hold upon exit T is an integer int 1 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 tIR Usage 1 string T Description T is a string a list of character codes The following properties hold upon exit T is a list of character_codes list 2 Usage 2 string T Description T is a string a list of character codes The following properties hold upon exit T is a list of character_codes list 2 predname 1 REGTYPE Usage 1 predname P Description P is a Name Arity structure denoting a predicate name predname P A atm P
172. tions except for brief quotes independently of the representation 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 t
173. 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 implemented via existing el packages such as word help written by Jens T Berger Thielemann jensthiCifi 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 8 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
174. troduction to the subject and some more examples please see the document An Assertion Language for Debugging of Constraint Logic Programs Technical Report CLIP2 97 1 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 ules 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 var 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 38 The Ipdoc Documentation Generator 4 3 Usage and interface assertio
175. ule autodocformats See the description of the imported predicates for more details and descrip tions of the interface A default definition of this module is provided in the autodocformats library 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 88 The Ipdoc Documentation Generator 13 1 Usage and interface autodoc e Library usage use module library autodoc e Exports Predicates autodoc 10 generate man page 5 generate description 6 generate info dir entry 5 rewrite docstring 4 Regular Types modtype 1 Multifiles library directory 1 e Other modules used Application modules lpdoclib autodocformats lpdoclib comments System library modules Streams ttyout format aggregates read errhandle dec10_io compiler compiler assertions assrt lib compiler c itf assertions assertions props messages filenames lists terms system pretty print vndict Internal engine modules arithmetic atomic basic attributes basic props basiccontrol data facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing 2 13 2 Documentation on exports autodoc autodoc 10 PREDICAT
176. which is included in source form below Comparing this code with the output in the following chapter illustrates the use and some of the capabilities 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 list 1 q 1 q 2 r 1 og 1 t 5 u 3 w 1 p 5 long 1 assertions basicmodes functions regtypes hiord Some properties that the current CiaoPP analyzers understand natively use module library assertions native props We import two types list 1 and list 2 now in basic props which is exported by default from assertions hh We reexport list 1 reexport library engine basic props list 1 use module bar ensure loaded foo commment declarations provide additional information comment title Auto Documenter Output for the Example Module comment author Alan Robinson comment author David H D Warren doc can be used in place of comment doc summary This is a brief summary description of the module or file In this case the file is a library comment 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 commen
177. 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 undefined Run time checking of assertions page undefined 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 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 closed 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 t
178. y 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 of 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 Checks that L is of length N Chapter 4 The Ciao assertion package 39 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 pred AssertionStatus 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 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 assertion
179. y modules strings Internal engine modules arithmetic atomic_basic attributes basic_props basiccontrol data_facts exceptions io aux io basic prolog flags streams basic system info term basic term compare term typing J 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 comment 2 declarations and assertions These character strings can include certain formatting commands e All printable characters are admissible in documentation strings except e and To produce these characters the following escape sequences should be used respectively 00 01 and 24 The Ipdoc Documentation Generator 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 CcommandA 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 or
180. zed list begin enumerate marks the beginning of an enumerated list Each item should be in a separate paragraph and preceded by an item 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 itemtert command 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 fixed format text such as a program example A fixed width typewriter like font is used end verbatim marks the end of formatted text Chapter 3 Enhancing Documentation with Machine Readable Comments 27 begin cartouche marks the beginning of a section of text in a framed box with round corners end cartouche marks the end of a section of text in a framed box sectiont tert 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 subsection tezt starts a subsection whose title is text footnote text places text in a footnote today prints the current date hfill introduces horizontal filling space may be ignored in certain

lpdoc Reference Manual - pdf

Contents

Download Pdf Manuals

Related Search

Related Contents