[kde-guidelines] CVS

[Lauri Watts]

On Thursday 28 October 2004 19.36, Frans Englich wrote:

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

Sorry, I wasn't clear: Yes, this was in fact the plan, the common directory is 
for things that really should be shared, like the header graphics, and 
callout graphics and, well, pretty much what's in it now.

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

Why do we need different versions available?   CVS (or SVN) takes care of the 
sources.

If HEAD is the current version of guidelines, and guidelines by their nature, 
supercede previous versions, why would someone want to look at older 
versions?  I am editing this mail backwards, so "I already asked this later" 
heh, but please do explain.

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

I did forget these were there, I'll look at them in the morning (it's really 
late here!)  I had no special guidelines in mind, so long as the names are 
unique, the rest is gravy.

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

The actual XSL to do the fancy stuff is two files, both under 100 lines long, 
and very likely to stay that way.  I could in fact reduce it further, but 
it's small enough that's going to stay pretty low on the priority list.  It 
does reuse (via xsl:include and xsl:import) quite a lot of the existing KDE 
XSL, .

> ls www/areas/usability/hig/stylesheets/
> CVS  common.xsl  pdf.xsl  xhtml.xsl
>
> > 	/src/
> > 		/index.docbook [3]
>
> What component is index.docbook? A set?

Yes.  Semantically that's what this is, a set of related books.

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

All the same to me.  Meinproc has problems with the filenames, but this is so 
far using xsltproc anyway.

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

This one is non-negotiable and yes we took your input onboard last time it 
came up, and did seriously consider it.  

Entities, and they are not huge - honestly.  

After speaking to the maintainers, and considering the issues, they would in 
fact prefer less files rather than more, so individual validation is not 
especially important.  

They'll still be relatively huge if it's all in one file, or in fifty.  We 
(KDE)  have some book length docs that are managed in 3-5 files, have 
multiple authors, and work out just fine for everyone.   If in future a 
technical requirement that can only be solved by XIncludes comes up, we can 
revisit it, but I have never met one yet.

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

Yes.

> /				# 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).
Habit.  It's also logical to claim it should be index, since a: that's what 
the html is called, and b: all the other KDE docs anywhere, have an 
index.docbook, so it's the one everyone knows as the "start from here" point.

> /X.X/				# Output of version X.X
Can you explain why having outdated versions available would be useful?
I'm not sure I understand.  This is pretty simple to do, duplicate the 
directory hierarchy under the version number, but I just don't see it's 
value.  Any new guidelines should be superceding entirely the old ones, and 
if it's just for comparison purposes, changes from previous versions should 
probably be explained (with their rationale) in the document itself.  I feel 
like I'm missing something obvious here.

> /backend/			# CSSs, XSLs, javascripts, whatever

s/backend/common, just because that would save me one more thing to hack 
around in the styles (and leave them as much as possible 

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

Initially because some people don't like PDF's, and also don't like having to 
click next when they can just scroll down, and it leaves the door open for 
conversion to other formats (.pdb files, rtf, wordml even.  Most formats, the 
first conversion filter written is plain text, and the next one out the door 
is html. )

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

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.

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

As I thought.

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

Glossary, ready (no entries, but it's there)
Index, ready (no entries, but there and ready to go:)

I can pretty simply turn a <classname>KSomething</classname> into a link 
directly to the API documentation.  Except when I can't, because the 
KSomething is actually a struct, and /class/KSomething != /struct/KSomething.   
So some of them really should be <structname> - is there in fact a way to 
tell them apart without looking each and every one of them up in the API docs 
by hand first?  

I didn't even try figure out functions yet, I figure getting classes/structs 
working first is enough challenge at a time.  RSS hadn't even occurred to 
me :)

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

Ain't it great indeed :)

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/20041029/e63fdb4a/attachment-0001.pgp