Future i Information : Creating documentation

On Future i Information

This is an example document for the Future i info site. It demonstrates the simple documentation API. A style guide ought to follow in due course, after some discussion. The stylesheet will continue in development.

Don't forget if you write nasty, bad or evil HTML you will most surely get shouted at. This shouldn't make you worried, we're all trying to learn, but try and keep it simple and compliant. To avoid nasty HTML <font> tags et al) util_show_source munges the output from PHP's show_source. I'll rewrite the internal PHP function sometime, and submit it back to the PHP folk, but for now it just does a bunch of regexps (util_show_source will be part of the Fi kit when it gets out the door; if you are on budvar now then just get your includes and paths right).

What is possible is most obviously seen from the source:


<?php
require_once("markup.inc"); 

// Note that we could add definitions of particular
// authors in an include, then reference them by some
// short name here. It'd be pass by value, but not so
// bad, IMHO
/*
authors is a list of assoc arrays each with:
    name
    email (optional)
    uri (optional)
    If email is specified it is shown and linked
    If uri is given then the name is linked to it 
           (some home page, summary of their work, etc.) 
*/
$authors = array(0=>ashok);


// We build a single assoc array once, and use it for
// header, footer and index generation.

/*
doc_info expects a number of fields:
title is the readable title of the document
stylesheet (optional) allows you to secify an alternate stylesheet
authors as above
stylesheet and any other urls should be encoded for output already.
Everything else will be HTML entity encoded here.
*/
$doc_info = array(
    uri => "create-doc",
    authors => $authors,
    title => "Creating documentation",
    status => FI_STATUS_DRAFT,
    extra_status => "",
    ack => "",
    desc => "How to format a document to be auto-indexed for Doc server"
);

// This section is vital, since it ensures the index
// can be generated on automatically. 
if ($processing_index_page) {
    return $doc_info;
    exit();
}

write_doc_header($doc_info);
?>
<p>
This is an example document for the Future i info site.
It demonstrates the simple documentation API. A style guide
ought to follow in due course, after some discussion. The
stylesheet will continue in development.
</p>
<p>
Don't forget if you write nasty, bad or evil HTML you will most surely get shouted at. This shouldn't make you worried, we're all trying to learn, but try and keep it simple and compliant. To avoid nasty HTML <code>&lt;font&gt;</code> tags et al) <code>util_show_source</code> munges the output from PHP's <code>show_source</code>. I'll rewrite the internal PHP function sometime, and submit it back to the PHP folk, but for now it just does a bunch of regexps (<code>util_show_source</code> will be part of the Fi kit when it gets out the door; if you are on budvar now then just get your includes and paths right).
</p>
<p>
What is possible is most obviously seen from the source:
</p>
<blockquote class="snippet">
<?php
util_show_source($SCRIPT_FILENAME);
?>
</blockquote>
<?php
write_doc_footer($doc_info);
?>