We are porting a legacy application to oacs4 at the moment and I was thinking about user documentation. This system has documentation existing already on the page level, describing for every page, what is does.
So I was thinking, maybe we could just integrate that into ad_page_contract and get a nice help document automatically. So I wonder if it would be better to use
@user_doc blabla
or
} -user_doc {
blabla
}
And I'm not yet sure, how to use retrieve the documentation. It could be gathered on server startup like ad_proc documentation, but that would further slow down the startup process, maybe it could be a variable passed, that will be handled by ad_page_contract, like calling the same page with an extra parameter like
<a href=[ad_conn url]?show_user_doc=t>Help</a> as part of the template and have ad_page_contract recognize that variable on itself, display the help contents and stop processing the page.
I think, this documentation would be very good to have in ad_page_contract (that's what it's for), so when you edit a file, you always know what this page is for. but I imaginge this docs to be in a more user-friendly manner, not just technically speaking as the normal doc-block.
