[Phpmyadmin-devel] RE: [Phpmyadmin-devel] suggestion for Documentation after 2.3

[Beck, Mike]

> 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.

exactly

> There are quite a few anchors already, and it would not be 
> too hard to add
> more.

jup, it will just need a lot of patience...
 
> <?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
> ?>
something like that. Only if Js is enabled it should only point to # and if
there is no js than we don't need to add the onClick. Do we allready have
some js-checking? after all we are using some js every now and then.
And of course we will have to give the section (=filename) as well, and the
function might have to add the language.

> 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.

agreed. though what i am thinking of is a graphic of 10*10 pixels (because i
want to also have it on the side of inputs) and just a text ? is not really
obvious enough (that's for the alt in case you also switched off graphics
;-)

> >  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:
...
> 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.

yes, there even i agree XML would be a good move *lol* well i wanted to do
some reading on this topics anyway..
 
> >  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.

at least then we should think of having the files for different languages.
(allthough i expect it would be ok to have the install only in english). but
then there is two problems:
the whole doku in all the languages would be quite a package, so i'd suggest
that the documentation would be split from the main package and is
downloaded seperately in the language the user wants (this also spares us to
have 30 or 40 copies of the english text at the beginning while there is no
translation for some language and we need a file with that name ;-)

and we'd have to think of a way to handle the translations .... what i could
imagine would be to have all strings in a database and do a script that
would enable the translators to translate them online and creating their
languagefile out of it?

simple draft:

table docu
str_id	section_id[enum]	place_id	string
0000001	tbl_qbe		1		Heading 1
0000002	tbl_qbe		1.2		<dt><dd>bla bla....

table transl_chines
str_id	translation
0000002	asdfhlsajfh

so when creating the languagefile the script would not find 0000001 in the
transl so it takes it from the table docu (which can be done with a simple
left join transl_chines where str_id is null) and the other from the
translation.

additionally a script like that could of course easily provide the text in
all needed charactersets.

hm.... once again something which might be an idea for a splitted project -
there might be other people apart from PMA that might have a use for that.

-- 
Mike Beck
mike.beck at users.sourceforge.net