[kde-guidelines] CVS

[Frans Englich]

On Friday 29 October 2004 11:26, Olaf Jan Schmidt wrote:
> [Frans Englich, Freitag, 29. Oktober 2004 04:09]
>
> > > Fine with me.  There's probably only going to be a page or two at the
> > > top, since all the real content is in the docs themselves.  However,
> > > it is of course vital that things like the access keys and stylesheet
> > > changing are available, and the PHP framework does provide this.
> >
> > Vanilla Docbook sets access keys(remember the discussion on
> > kde-doc-english, where someone proposed a patch for adding access keys,
> > while it became evident that it was the customization layer that
> > overrode too much).
>
> The accesskeys on html pages from the docbook sources are different from
> those defined for kde.org. Is it possible to change the dokbook->html
> confersion process to also generate all the accesskeys listed at
> http://kde.org/media/accesskeys.php? Adding those to docs.kde.org and
> later guidelines.kde.org would be really good for consistency reasons.

Docbook have all its navigation elements covered, so the question is if we 
will have more than what default Docbook have(e.g. currently we don't have 
any of the navigation elements listed on that page, except those). If we add 
those navigation elements manually(with the customization driver), we'll 
subsequently have to add the access keys manually(no big deal). If we use the 
PHP framework, they come automatically.

Hence, the question is how the web site should look -- what navigation 
elements that will be there in addition. I would wait with anything big, 
until the developer.kde.org merge is done.

It would be practical and simple to use KDE's PHP framework, if only it wasn't 
such cumbersome :| 

Here's a description of the problem. A typical page looks like this:

<?php
$page_title = "Usability Books";
include "header.inc";
?>
<p>Content</p>
<?php
include "footer.inc";
?>

And the PHP code then inserts html, head, and body tags -- it's copy/paste. 
Hence, anyone who wants to do something more advanced than a table or a 
couple of paragraphs in the body, is on their own, since one cannot affect 
what is in the head tag(and that is a lot).

But, Docbook is integrated fine here:
http://usability.kde.org/hig/current/

So how's that achieved? (reading further hurts your health)

The Makefile rips off everything up to, and including the body tags(from the 
Docbook output), and the customization driver then inserts the PHP tags, such 
that the files finally served only have the html/head tags from the PHP 
code(and hence it's integrated). But, if I had designed the driver to use CSS 
or anything else, which Docbook would have putted in the head tag, I would 
have been smoked, since I had to remove those parts. Fun!

So the PHP framework is out of the question in this case, AFAICT.

I see the PHP framework as rather simple, it was written a long time ago, and 
doesn't play very well with XML, but saves one from typing(and the features 
it brings). However, it would be possible to make it play with XML/XSLT by 
refactoring out common parts, and making XSLT and PHP code reference those, 
such that the two approaches could coexist. But it's a larger work, and I 
would think it's better to wait with that, until the DKO merge.

So the question is what people want to do right now; I would use the docbook 
output, and add a couple of static html pages at the front(or simply the 
TOC). It will look grand anyway, with the current customization.

>
> Whether there are other accessibility reasons to have a seperate
> accessible verision depends a bit on how the "normal" html pages will be
> coded. I can only answer this after seeing this. Is there an example of
> the planned html code somewhere online?

The stuff Lauri have will probably be committed soon.


Cheers,

		Frans