(!*******************************************************
  * Mosel Example Programs 
  * ======================  
  *          
  * file mddoc.mos  
  * ``````````````   
  * Example for the use of the Mosel language 
  * (Use of annotations for documentation) 
  *                                   
  * (c) 2015 Fair Isaac Corporation  
  *     author: Y. Colombani, rev. Nov. 2018
  *******************************************************!)

model mddoc
version 0.0.3
!The following optional header is required only when building the PDF
(!@doc.
 @xmlheader
<!DOCTYPE Dash:manual SYSTEM "../Styles/moseldocpdf.dtd">
<manual id="mddoc" date="November 2018" title="An example of model documentation" author="Y. Colombani" author2="YvesColombani@fico.com" firsttitle="none" type="doc" mantype="ug" creation="2015" release="0.0.3">
 </manual>
 @xmlroot manual
!)

(!@doc.
 @title An example of model documentation
 @date November 2018
 @chapter Annotations for documentation
 @section Running <tt>moseldoc</tt>
 @p [XML]
 The <tt>moseldoc</tt> program takes as input a bim file produced from
 a Mosel model compiled with the <tt>-D</tt> compiler option.
 Generation of the documentation for this model is therefore obtained by
 executing the following commands:
 @p [SRC]
>mosel comp -D mddoc
>moseldoc mddoc
 @p
 The result of this process is an XML file (<tt>"mddoc_doc.xml"</tt>)
 and a directory containing an HTML version of the documentation
 (<tt>"mddoc_html"</tt>). The program will produce only the XML file
 (from a bim file) if option <tt>-xml</tt> is used and only the HTML data
 (from an XML file) if <tt>-html</tt>
 is selected. The option <tt>-f</tt> will be required to force the 
 replacement of existing files.
 @p
 As a Mosel program available in source form, <tt>moseldoc</tt> 
 can be adapted to fit specific user requirements. To re-generate the
 moseldoc executable use this compilation command (requires a C compiler):
 @p [SRC]
>mosel comp -s moseldoc.mos -o deploy.exe:moseldoc,css-z=moseldoc.css
 @p
 <b>Note for Xpress Workbench users:</b> 
 To enable the -D compiler option in Workbench open the <i>Run</i>
 menu and select the entry <i>Compiler Options</i>, enable the 
 <i>Generate Doc Annotations</i> option, then confirm with <i>Save</i>. 
 Click on the <i>Compile</i> button in the Workbench toolbar to generate 
 a BIM file that contains the documentation annotations.

 @section Automatic addition of annotations
 @p
 The documentation generation relies on annotations that are recorded 
 into the bim
 file. Some of these annotations are automatically produced by the Mosel
 compiler when it is run with the option <tt>-D</tt> (it is also possible
 to overwrite annotations set by the compiler).<br/>
 These are the automatically generated annotations:
  <dl>
  <dt class="DLItem">@doc.name</dt><dd class="DLText">model/package name</dd>
  <dt class="DLItem">@doc.version</dt><dd class="DLText">model/package version</dd>
  <dt class="DLItem">@doc.date</dt><dd class="DLText">generation date</dd>
  <dt class="DLItem">@doc.syntax</dt><dd class="DLText">subroutine prototype</dd>
  <dt class="DLItem">@doc.type</dt><dd class="DLText">entity type</dd>
  <dt class="DLItem">@doc.recfldtype</dt><dd class="DLText">record field type</dd>
  <dt class="DLItem">@doc.default</dt><dd class="DLText">parameter default value</dd>
  <dt class="DLItem">@doc.const</dt><dd class="DLText">constant value</dd>
  </dl>
 @p
 The special annotation <tt>@doc.autogen</tt> can be used to disable
 locally this automatic generation procedure (when it is set to 'false', the
 generation is disabled).
 @p
 Thanks to the automatic generation feature it is possible to produce a documentation for model source files that do not contain any annotations.

 @section Document structure
 @p
 The document is organised in chapters (<tt>@doc.chapter title</tt>),
 sections (<tt>@doc.section title</tt>) and subsections (<tt>@doc.subsection title</tt>).
 In each of these components, paragraphs are added using the marker <tt>@doc.p</tt>.
 By default, the paragraph content is expected to be valid XML but plain
 text can also be used by starting the paragraph with the <tt>[TXT]</tt> marker
 (in this case special characters like '&lt;' are not interpreted) and to insert
 code examples you need to start with the marker <tt>[SRC]</tt> (special 
 characters are not interpreted and spacing is preserved).
 @p
 Documentation contents (entities, function definitions and paragraphs) are
 automatically associated with the current subsection, section or chapter
 (depending on the last definition). It is also possible to specify
 a different location using the <tt>@doc.relocate</tt> annotation that
 must designate a target location in the document that has been defined 
 with <tt>@doc.location</tt>.
!)

(!@doc.
 @chapter The example
 @p
This entire document is generated from the source file
<tt>mddoc.mos</tt>. Please look at the model source to see which annotations
were defined to produce the output under this chapter.
!)
!@doc.section Parameters
parameters
 !@doc.descr short parameter description
 !@doc.value v1 possible value
 !@doc.value v2 another possible value
 !@doc.info some more explanation (longer text)
 P1="some text"
end-parameters

!@doc.section Constants and variables
!@doc.location vardefs
public declarations
 (!@doc.
   @descr short description of the constant set
   @info additional information
 !)
 S=1..10

 !@doc.descr an error code constant
 MYERR=11

 (!@doc.
   @descr a record type
   @recflddescr fld1 field description
   @recflddescr fld2 another field description
   @recfldval fld2 val1 meaning of a specific value
   @recfldval fld2 v2 another value for this <i>field</i> with a subroutine reference <fctRef>aproc</fctRef>
   @info further information
 !)
 rectype=public record
  fld1:integer
  fld2:string
 end-record

 (!@doc.
   @descr a record variable
   @recflddescr fldA field description
   @recflddescr fldB another field description
   @setby <fctRef>aproc</fctRef>
   @info @doc.value may also be used with a variable
   @info several @doc.info tags can be used for a given entity
   @info entities can be referenced: <entRef>rectype</entRef> !) recvar:public record fldA:integer fldB:string end-record end-declarations (!@doc. @section Subroutines @p [TXT] The list of subroutines below is automatically generated from the declarations appearing within the scope of this section !) (!@doc. @descr some short description @param i first parameter @param r second parameter @param flags some flags. Possible values: @paramval flags 1 first option @paramval flags 2 second option @err 33 error condition that can be set @err MYERR reference to an error code constant @return the truth @example Some descriptive text for the example @example [SRC] the example code is here @info useful information for <fctRef>myfunct</fctRef>
!)
public function myfunct(i:integer,r:real,flags:integer):boolean
 returned:=i>r
end-function

!@doc.group myfunct
!@doc.info <fctRef>myotherfunc</fctRef> is an alternative to <fctRef>myfunct</fctRef>
!@doc.info Up to 3 different subroutine names can be grouped
public function myotherfunc(i:integer):boolean
 returned:=true
end-function

!The following procedure will not be included into the doc
!@doc.autogen=false
public procedure hiddenproc
 a:=1
end-procedure
! re-enable automatic generation
!@doc.autogen

(!@doc.
  @descr Yet another routine
  @param s the only parameter
  @info should modify <tt>recvar</tt>
  @related <entRef>recvar</entRef>
!)
public procedure aproc(s:string)
 writeln(s)
end-procedure

!@doc.relocate vardefs
public declarations
  advar:string  !@doc.descr an additional variable
 end-declarations
end-model