ML-Module: doc_core Package: mldoc

Description

The core module of MlDoC . This module contains all basic functions and types used by all other frontend and backend modules.

Flow of processing string text:
  1. Split the string text in atoms divided by blank spaces.
  2. Translate these atoms in a structure tree.
  3. Convert the structure tree into the desired output format.

First the interface of the main structure_content type and the the main structure_block :

Programming Interface
type  structure_content     =     S_Empty |   Empty element
S_Text of (string list) |    Generic text: basic element
S_Body |   Document root
S_Title |   Document title
S_TOC |   Table of contents
S_Intro |   An intro paragraph
S_Package |    Package=Library
S_Program |   A program description
S_S1 |   Generic named section
S_Module |   A ML-module
S_Clib |   A C-Library
S_S2 |   Generic subsection
S_Function |   A function subsection
S_Type |   A type subsection
S_Value |   A value subsection
S_Class |   A class subsection
S_C |   C functions and variables
S_S3 |   Generic unit
S_Paragraph |   A named paragraph
S_Interface |   Generic Interface
S_Example |   Example preformatted paragraph
S_Preform |   Preformatted paragraph
S_S4 |   Generic subunit
S_Fun_Interface |    ML-Function interface
S_Val_Interface |    ML-Value interface
S_Type_Interface |   A ML-type definition
S_Exc_Interface |    Exception
S_Struc_Interface |   A type structure
S_C_Hdr_Interface |   C header interface
S_C_Fun_Interface |   C function interface
S_C_Var_Interface |   C variable interface
S_Class_Interface |   A ML-Class
S_Method_Interface |   A ML method of a class
S_Object_Interface |   A ML object of a class
S_Module_Interface |   A ML module interface
S_Attribute |   Text or other attributes changes
S_OList |   Ordered List
S_UList |   Unordered List
S_OpList |   Definition List
S_List_Item |   Unordered List item
S_Table |   Table body
S_TableHead |   Table header
S_TableRow |   A new table row
S_TableCol |   Table column data
S_TableNoRulers |   Don't put boxes around the table cells
S_Name |   Function, Type,... name
S_Mutable |   Mutable prefix
S_Private |   Provate prefix
S_Virtual |   Virtual prefix
S_CurArg |   Argument of a curried list
S_UnCurArg |   Argument of an uncurried list:tuple
S_RetArg |   Return argument of a function
S_NL |   Newline
S_TAB |   Text tabulation
S_Link |   Link
S_Comment    A comment
type  structure_block     =   {   mutable  s_parent: structure_block option ;
mutable  s_childs: structure_block list ;
mutable  s_content: structure_content ;
mutable s_attr: structure_attr list ;
mutable s_line: int ;   For error tracking
mutable s_name: string ref }    For error tracking

A string can be converted to an atom list with the atoms_of_text function, and the atoms_of_file functions reads text from a file and convert it to an atom list:

Programming Interface
[  atom_list : string list  ]  =  atoms_of_text
~text : string
[  atom_list : string list  ]  =  atoms_of_file
~fname : string

The atom list can now be converted to a struture_block tree with the tree_of_atoms function. This function uses the parse generic text parser function. Finally, a structure_block tree can be printed in symbolic form with the print_tree function.

Programming Interface
[  unit  ]  =  parse
atom_list : string list ->
cur_block : structure_block
[  struc_tree : structure_block  ]  =  tree_of_atoms
~atoms : string list
[  unit  ]  =  print_tree
structure_block

Sometimes it's usefull to convert only a part of the full document. For this purpose, all back end functions have the section_names list argument to tell the backend the current section environment. The Doc_core module defines the section structure and the section_names types. The structure is only for internal use in the backend.

Programming Interface
type  section_names     =     Sec_s1 of string |
Sec_s2 of string |
Sec_s3 of string |
Sec_s4 of string |
Sec_package of string |
Sec_program of string |
Sec_module of string |
Sec_function of string |
Sec_type of string |
Sec_val of string |
Sec_class of string |
Sec_cint of string
type  section     =   {   mutable  sec_parent: section ;
mutable  sec_childs: section list ;
mutable  sec_name: string ;
mutable  sec_type: string }

A short example follows to show the processing flow to translate a help text file to a structure_block tree.

Example 
let al = atoms_of_file "mldoc.man" ;; 
let st = tree_of_atoms al ;; 
html_of_tree ds [HTML_single_doc "mldoc_man.html"] [];; 
tex_of_tree ds [TEX_doc_name "mldoc.tex"; 
        TEX_color; 
        TEX_link_ref; 
    ] []; 
text_of_tree ds [TEXT_doc_name "mldoc.txt"] [];



UP Package: mldoc