[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