[kde-guidelines] CVS - Attempt to summarise

[Frans Englich]

On Thursday 04 November 2004 10:56, Ellen Reitmayr wrote:
> On Wed, 2004-11-03 at 22:18, Lauri Watts wrote:
> > Exactly correctly.  So I will hunt down Aaron and coordinate getting this
> > stuff into CVS asap.
>
> I've started to map the TOC into files, plus added some comments on what
> should be in the concerning chapters/sections and TODOs. Still far from
> being complete, but a base to be worked on.
>
> With respect to file naming conventions and writing guidelines: I more
> or less adopted Frans' GUIDELINES from /www/areas/usability/hig/src. But
> for the naming I wonder if it is possible to use underscores instead of
> dashes to separate chapter-names from sect1-names from sect2-names etc.
> E.g. 'menus_designing-menus_menu-strucure' instead of
> 'menus-designing-menus-menu-structure'. It would increase readability,

You are referring to file names, and not id tags, right? Your readability 
problem comes from that you want to use several words per chapter/sect and 
hence needs a method to separate them(AFAICT). My guidelines said "Don't use 
all the words in a chapter/section title for its filename" and hence this 
problem didn't exist. It's a matter of how verbose one wants to be.

The one-word variant is a bit simpler, but I don't think it matters much. 
However, important is that the naming scheme for id-tags are identical, such 
that they are consistent.

For example, to paraphrase your example above; the id tag for an sect2 titled 
"Menu Structure" in sect1 called "Designing Menus" in chapter "Menus" would 
be called "menus_designing-menus_menu-structure". In my scheme, it would 
probably be called "menus-designing-structure".

(BTW, I think we should use <section> instead of <sectX> unless someone 
objects, since they aren't specific on what level they are in. FYI )

> but I'm not sure if that would hurt any conventions or technical (CSS?) 
> restrictions.

No, no technical problems. Dashes and underlines are almost always accepted 
characters for identifiers, be it file systems or programming languages.


Cheers,

		Frans