[kde-guidelines] CVS

[Frans Englich]

On Thursday 28 October 2004 23:43, Lauri Watts wrote:
> 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.

Ah ok, that's a good separation indeed.

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

Right, the sources are cool.

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

Our Guidelines aims for professional standards, and to be used in serious 
situations. A 3rd party want to work against a static document, and be able 
to say "We conform to KDE HIG specification version X.Y". For example, it's 
frustrating to work against a document which at one day say "ABC" and the 
next day it says "ABD". It doesn't matter that much for KDE's fluid 
development(perhaps for the bigger suites) but for folks outside, I think it 
does.

Similarly, it's difficult to refer to the HIG when it's state is never 
known("Ohh, my print out must be old," "When did you download that off-line 
version?,", "<long discussion>, ohh, we must be talking about different 
things, my version don't say that")

The GNOME folks do versioning, but what the heck, they were wrong about using 
a bug DB too(ka dum bing).

Also, we need some space for developing. I know, I know, we will review 
patches _thoroughly_, but if we don't have the possibility to screw up one 
single time, or be even the smallest experimental, it will be tough. If every 
commit doesn't have to be release quality, it will be more relaxed.

In addition, it adds structure in development; we can plan what to "implement" 
for a version, and have a well defined goal. It's also possible to do proof 
reading, quality assurance, when a document can be stable, and not be fluid.


Aaron wrote in the summary of the aKademy meeting:
"we expect them to be actively maintained and developed over time, however, 
and therefore they will be versioned much as we do with our software 
including having both a stable and a devel (HEAD) branch in CVS for these 
guidelines."

So.. I'm a little bit confused here. I see some different combinations: 1) 
Lauri slept on the meeting; 2) Aaron was drunk when he wrote that. Or perhaps 
vice versa? Or both options for both of you? :)))

What are your thoughts on this, Aaron? (well, perhaps the former paragraph ;-)


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

I think it's a good idea. For example, the old HIG didn't have many images but 
it was nevertheless tricky to sort them out with the short names they had. 
(Having developer documentation is a good thing, imagine if _all_ of us gets 
hit by a bus :), or our natural slipporing memory over time)

<SNIP agreement on XHTML>
>
> > 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 

So, for how long will it be we vs Frans? Or how should I interpret it? I 
disagree with you, you disagree with me, but for whatever reason you have the 
right to overrule me? In what other cases doesn't developers wait for 
consensus before pulling decisions?

(the topic in question is a non-issue, but if future contributors which are 
not hard-skinned like me, are to hear that, they probably won't stay long. 
And I neither like it.)

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

Right, it's easily changed. But it's nevertheless silly :) You may talk as 
much as you like about that the maintainers like few files, or that it was 
suitable in some other case -- because it's not relevant. For example, it 
won't result in more files by using XIncludes, right?

Let me put it this way: If I patched the file to use XIncludes, because I find 
it comfortable to stay a little bit modern, flexible, be in the XML camp, and 
have the comfort of validating files separately, would it then matter to 
anyone else involved? :) Would the maintainers have /more/ files to edit? 

Don't worry, I'll live with system entities, but I wonder: Why /not/ use 
XIncludes? What's the negative about them, and what's better with system 
entities, which makes us choose them? (I simply don't understand why they 
should be favored)


<SNIP Lauri's explanations to my questions which I agree/accept>

> 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). Dunno 
about CSS selection, though. Integrating KDE's PHP framework would most 
likely break the javascript/CSSs. I think it's easier to implement CSS 
selection in the customization layer. (I'll have a look when it's in CVS) 

<SNIP>
> I can pretty simply turn a <classname>KSomething</classname> into a link
> directly to the API documentation.

Nice, can you post the template? I had a look, and I couldn't find out how to 
do it without knowing what library the class was part in, in order to 
generate a proper URL(functions was even worse for me, they needed the class 
& library).

Also, could we use <section> instead of <sectX>? Would save work when 
reorganizing, and easy to do when we're from scratch(sectX's will probably be 
obsoleted in newer versions, also).

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

You mean by looking at its name? I think it is de facto standard in Qt & KDE 
to capitalize the struct(structname) and members(structentry), but without 
initial K. For example: KMessageBox::ButtonCode{Ok, Cancel, Yes, No, 
Continue}.

Marking it up properly is not a bad idea anyway, though.

BTW, do you know if it's possible to automatically indent XML, without making 
space appear in inappropriate places? (link like elements etc.)

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

Yes, the more website heavy things can later be added when we've integrated 
with developer.kde.org. It could have a news engine where developer news 
could be posted. For example, there's tons of usability articles written over 
the Internet which should be exposed for the KDE developers, but it's 
inappropriate for the Dot. There could be different RSSs; for kde-cvs, 
display newly added icons, documentation updates etc. (and hence build a 
really good developer portal, with high information density.)


Cheers,

		Frans