[kde-guidelines] CVS

Frans Englich frans.englich at telia.com
Thu Oct 28 19:36:35 CEST 2004


On Thursday 28 October 2004 01:06, Lauri Watts wrote:
> 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 :)

Great work :)

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

Yes, hopefully we'll have svn at some point.

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

When I edited the old HIG, I rigged this directory structure:

stylesheets/*.xsl
src/*.xml			  // docbook sources
src/images/*.png
current/{*.php,*.pdf} // "HEAD"/"draft" version
1.0/{*.php,*.pdf} 
X.X/{*.php,*.pdf}	  // Different versions of the HIG


1) Since we most likely will have many images, wouldn't it be a good idea to 
separate those into src/, and possibly other sub directories, in order to 
avoid name clashes, and not flood common? Also, it can be a good idea to 
separate the sources(images) from whatever technical files for running it(PHP 
includes, CSSs, XSLs, etc.)

2) How have you thought to handle different versions of the HIG? The output as 
well as the sources? The problem with doing tagging, is that generation have 
to be done from a certain check-out, instead of a certain directory, but I 
nevertheless think tagging/branching is the best way to go. The output must 
go in different directories, though.

3) What's your plans on naming schemes for images, xml files as well as 
id-tags? I've written about this many times before, but you can have a look 
at the naming schemes specified and used in:
www/areas/usabiliy/hig/src/GUIDELINES
www/areas/usabiliy/hig/src/images/

4) I splitted the stylesheets into three different, such that common code was 
in one, which the PDF & XHTML stylesheets then included. It's a practical 
modularized design(perhaps you've already done it). For inspiration, see:

ls www/areas/usability/hig/stylesheets/
CVS  common.xsl  pdf.xsl  xhtml.xsl


> 	/src/
> 		/index.docbook [3]

What component is index.docbook? A set?

> 		/accessibility/
> 		/usability/
> 	/html [4]
> 	/plainhtml
> 	/multi-html

Does html mean HTML or XHTML? I think it could be a good idea to go for XHTML, 
one reason is it makes the future easier if we're on the XML side. If HTML, 
does XHTML cause trouble in anyway?


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

Cool.

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

Do you use XIncludes or system entities? Since the sources will grow huge, it 
can be practical to validate files individually, instead of having to load 
all the sources each time.

>
> [4]  The filenames are guaranteed (or the original docbook will be invalid)
> to be unique,

You use the use.id.as.filename parameter, I assume.

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

Yes, getting the directories right is a mess. I'm just thinking out loud, a 
layout which takes versioning into account(ascii art):

/				# Web site root. That's www/areas/developer, right?

/src/guidelines.xml		# The top file(guidelines instead of index, since 
				# it's logical instead of specific on format).
	
/src/accessibility/*.xml 	# A11y stuff	
/src/hig			# 
/src/hig/images/		# Same for a11y and other guildeines, you get the point.
/current/			# Output for the HEAD version(pdf, kdevelop,
				# khelpcenter, xhtml)
/X.X/				# Output of version X.X
/backend/			# CSSs, XSLs, javascripts, whatever

Since we have _all_ sources in one docbook document, that means all id's are 
unique, and there will hence not be any name clashes when everything is in 
one directory(also, if the naming scheme is as the files I quoted above, that 
means they are logically structured too). I think it's easier than to 
configure docbook to generate into different directories. Since there is no 
name collisions, one doesn't have to 

Do we need anything more than chunked xhtml and PDF(and kdevelop/khelpcenter)? 
I don't see how one page, docbook.xsl, generation would be useful -- it's 
impractical to read, and printing is best done with PDF, AFAICT. In what 
scenario would it be used?

AFAICT, IMO.

>
> That would leave the files in the root directory (the usual php and html
> stuff I suppose - I am completely PHP challenged, 

I think we should try to avoid KDE's PHP framework :) I integrated the old HIG 
with PHP and it was a pain and ugly.  If we could serve plain 
XHTML/javascript, that would be nice.

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

Yes, we don't really know when and how that project starts, so going past it 
is probably a good idea. When it starts, svn is probably there, so doing an 
reorganization is probably not that cumbersome.

Do you guys and girls realize how cool this will be? :) Everything nicely 
formatted, high quality PDF output, a developer reference at some point in 
src/devref.. , a nice index, glossary, <class> and <function> links to the 
API reference, proof read, an RSS with updates... Err.. I need to take a cold 
shower..

And the best thing of all.. It's the new KDE Book growing, which one day will 
go to print -- without getting old.


Cheers,

	Frans



More information about the kde-guidelines mailing list