24 Jul
2002
24 Jul
'02
1:52 p.m.
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:
1) do you agree to try to go in this direction
Yes.
2) 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.
3) 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.
--
Robin Hugh Johnson
E-Mail : robbat2(a)orbis-terrarum.net
Home Page : http://www.orbis-terrarum.net/?l=people.robbat2
ICQ# : 30269588 or 41961639