KayaDoc module
This module contains functions to convert documentation files created with kayac's -xmldocs option into HTML or man page format. The source of the kayadoc2man program in the tools directory of the Kaya distribution may be useful for examples of use. It also provides an API to examine the documentation for writing other formats - see the ElementTree module for details of processing the XML representation.
HTML documentation produced with this module may be seen on the Kaya website, and man pages are installed in prefix/man/man3/*.3kaya.gz by the Kaya installation process.
// generate HTML document for a particular function
doc = readDoc("MyModule.xml");
entry = findEntry(doc,EntryLocation("myFunction",0,EntryFunction));
appendExisting(html.body,describeFunctionHTML(entry));
// get a list of all the data types in a module
// and summarise them in HTML
doc = readDoc("MyModule.xml");
ds = listDataTypes(doc);
for d in ds {
htmliseContents(d.summary,html.body,linkFn);
}
// get the short summary for a module in man page format
doc = readDoc("MyModule.xml");
summ = extractSummary(moduleSummary(doc));
manstr = manSummary(summ)A specification for the -xmldocs format can be found in the XMLDOCS file.
Type Synonyms
APIDoc=ElementTree
Data types
- KayaDoc::Constructor - A constructor function
- KayaDoc::DataSummary - A data type
- KayaDoc::EntryLocation - An entry within the document
- KayaDoc::EntryType - Types of documentation entry
- KayaDoc::ExceptionSummary - An Exception
- KayaDoc::FunctionSummary - A function
- KayaDoc::TypeSynonym - A type synonym
Exceptions
- ModuleContext - EntryModule not allowed
- NoSuchEntry - No such entry
Functions
- ElementTree describeDataHTML(ElementTree dat,String(String, Int, EntryType) linkto) - Describe a data type in HTML
- String describeDataMan(ElementTree ddata,String modname,String authors="") - Describe a data type in man page format
- ElementTree describeExceptionHTML(ElementTree exc,String(String, Int, EntryType) linkto) - Describe an Exception in HTML
- String describeExceptionMan(ElementTree excdata,String modname,String authors="") - Describe an Exception in man page format
- ElementTree describeFunctionHTML(ElementTree fun,String(String, Int, EntryType) linkto) - Describe a function in HTML
- String describeFunctionMan(ElementTree fundata,String modname,String authors="") - Describe a function in man page format
- Maybe<ElementTree> extractSummary(ElementTree part) - Find the
summarycomponent of a documentation block - ElementTree findEntry(APIDoc doc,EntryLocation entry) - Find a documentation entry
- Void htmliseContents(ElementTree tree,ElementTree addto,String(String, Int, EntryType) linkto) - Convert the contents of a (e.g.)
<prose>section to HTML - [DataSummary] listDataTypes(APIDoc doc) - Lists data types in a module
- [ExceptionSummary] listExceptions(APIDoc doc) - Lists Exceptions in a module
- [FunctionSummary] listFunctions(APIDoc doc) - Lists functions in a module
- [TypeSynonym] listTypes(APIDoc doc) - Lists type synonyms in a module
- String manFilename(String name) - Return the man page name for a function or data type
- String manSummary(ElementTree summary) - Convert a summary to man page format
- String manTime() - Return a time for a man page
- String maniseContents(ElementTree summary,Bool preformatted,String manstr,String modname) - Convert the contents of a (e.g.)
<prose>section to man page format - ElementTree moduleSummary(APIDoc doc) - Get the summary of a module
- APIDoc readDoc(String filename) - Read an -xmldocs .xml file
- APIDoc readString(String xmlstr) - Read a String from an -xmldocs file
- Void toHTML(ElementTree div,ElementTree comment,String(String, Int, EntryType) linkto) - Convert API documentation to HTML
- String toMan(ElementTree div,String modname,String authors) - Convert API documentation to man page format
