[kde-guidelines] CVS

[Lauri Watts]

Hi all,

This is no less than the third time I have written this email, I do hope it 
gets actually sent this time!  In any case, what there already is of the HIG 
has been floating around my hard drive for far too long, and it's holding up 
getting more writing done, so I'd really really like to get it into CVS so 
I'm not the one holding up the works all the time :)

I would like to commit to CVS the stuff I have sitting around here for the 
HIG.  Currently it's a few docbook files, the support XSL, CSS and JavaScript 
for it, and a very simple shellscript that generates output files in various 
formats.   The actual layout is rather flexible, but will be a beast to 
change in CVS later, so it's best to decide now.

I can right now generate "pretty multi-page HTML" (the one with the hide/show 
sections and fancy sidebars), Plain multi-page HTML (looks just like the KDE 
Docs in KHelpCenter, and with all content visible), all-in-one-page HTML 
(very plain, suitable for printing) and PDF (there's a buglet in the PDF 
currently that makes it not create a TOC, but nothing that can't be fixed)  I 
also have a half working XSL to pull out just the guidelines from the docs, 
and present them as a checklist to work through.  There are potentially other 
output formats, so whatever is decided, it needs to be able to scale up some.

Each version has links that resolve inside it's own version, and none of them 
specially care where they are, although each one needs to be in a different 
subdirectory, since there are otherwise filename clashes.

I'd like to make this structure:

/ [1]
	/common/ [2]
	/src/ 
		/index.docbook [3]
		/accessibility/  
		/usability/
	/html [4]
	/plainhtml 
	/multi-html 
	/pdf

Notes:
[1] The root of the website: I imagine this would contain entry points to the 
different versions of the guidelines, and probably provide downloadable and 
installable-into-khelpcenter/kdevelop versions 

[2]  The support files and shared content (graphics, styles, etc) for all the 
html versions

[3]  The sources - in order for the links to resolve between the different 
books (ie, links from the usability guidelines to content in the 
accessibility one) there needs to be an overall 'meta' document that includes 
them all into itself - under that, the other content can be kept quite 
separate from each other.

[4]  The filenames are guaranteed (or the original docbook will be invalid) to 
be unique, so having all the html content in one directory is not really a 
problem, since there would be entry points from the website itself directly 
into the applicable pages.  The url's would probably look something like:
http://guidelines.kde.org/html/accessibility.html (for say, the introduction 
into the accessibility book) and 
http://guidelines.kde.org/html/usability.html for the usability one.  

I expect here I can also tweak the stylesheets so the accessibility and 
usability guidelines go into separate subdirectories, so it'd be 
"http://guidelines.kde.org/html/accessibility/<something>.html" for a page in 
the prettified accessibility guideline book, and 
"http://guidelines.kde.org/plainhtml/accessibility/<something>.html" for the 
same content in the plainer (but more accessible) version.  

That would leave the files in the root directory (the usual php and html stuff 
I suppose - I am completely PHP challenged, so someone else is going to have 
to take care of that part) and those under src/ that would be edited by the 
maintainers, and the rest is generated.  I would be happy to see it generated 
by hand, as required, for the present - if the directory structure is fairly 
sane, we can probably retrofit it with auto-generation stuff when we have 
some, and if not, well, mod_rewrite is a powerful friend to deal with that.

Regards,
-- 
Lauri Watts
KDE Documentation: http://docs.kde.org
KDE on FreeBSD: http://freebsd.kde.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-guidelines/attachments/20041028/5d82fe9d/attachment.pgp