On Wed, 24 Jul 2002, [utf-7] Beck, Mike wrote:
what i think should still be improved is the way to get to the documentation... at the moment we basically assume (hope/pray whatever) that anybody has read the document fully and still remembers it when he uses PMA.
While that may be true of most people that install phpMyAdmin themselves, it is not true if they are installing it for an ISP type setting, where there are other users besides the one that installed it.
then we would 'just' have to go through the docu and enter lots of anchors so we can call this function at all places throughout pma to show the user an easy way towards the docu.
There are quite a few anchors already, and it would not be too hard to add more.
idealy a ? icon should be beside every user input field. now this would require some more docu +AF8-and+AF8- i really think by then we should split up the docu into smaller parts, so that we don't need to send the whole docu file every time, so it would be something like: call+AF8-docu(+ACQ-topic,+ACQ-anchor).
I like the idea of splitting it up, as that makes it easier to manage as well.
i expect it will take some time until this is fully realized, but i'd suggest i'd do a function for it after 2.3.0 and start splitting the docu and then everybody could just try to keep in mind to add some functioncall if he stumbles across some place in the source that needs explanation, so it will get better after time.
in a library: <?php function PMA_HelpLink($ref) { globals $cfg; if ($cfg['Display_HelpLinks']) { $str = '<a href="Documentation.php#'.$ref.'" onclick="..."><sup>?</sup></a>'; } else { $str = ''; }
return $str; } // end of the "PMA_HelpLink()" function ?>
I have the configuration variable there on purpose, as in some cases I run with limited screen space, and I would want to turn off the help links, as I know what I am doing.
so:
- do you agree to try to go in this direction
Yes.
- wasn't there some thought on having the docu in a different format?
(sgml, xml or whatever)
Yes. No format was decided on. I'd be in favour of having the master document in SGML/XML, split up into little sections. Possible directory structure:
Documentation/ xml/ html/ text/ (etc for each format)
under each format: english-iso-8859-1/ japanese-euc/ (etc, so that we can have translated Documentation)
Under each language (files): Index Requirements Introduction Installation Configuration FAQ Developers Credits
I think XML masters would be ideal, as with XSLT stylesheets on our master side when we are rolling a package, we can build all the documentation easily. There would also be room to produce more formats easily from the XML, such as Info, LaTeX and PDF. I don't know if one can do this from SGML or not.
- i expect nobody ever really hoped we could get the whole docu
translated, or?
It will be a slow process for documentation, but it can be done in the long term.