In the beginning

--Boundary-02=_ohQQ+O04PCvMY34
Content-Type: text/plain;
  charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Content-Description: signed data
Content-Disposition: inline

Hi all,

I wasn't on the list yet when Aaron wrote his mail, so excuse thread breaki=
ng=20
and strange quoting.

> o A document format. We need to settle (quickly) on a final document form=
at.=20
> Docbook is a candidate, but we need to look at what sort of methodology w=
e=20
> wish to employ. Do we want to work on both documents in parallel files, o=
r=20
do=20
> we want to work on folding both documents into one "metafile" that can be=
=20
> processed to present either a KDE- or GNOME- specific final result. The=20
> latter sounds more ambitious to me, but also perhaps a good way of doing=
=20
> things if only because it allows us to truly share the common parts of th=
e=20
> resulting documents.

I can't see any reason to not use DocBook.  If another format is at all=20
useful, there either are stylesheets to get there, or someone can write xsl=
t. =20
The advantages are enormous: The content is already mostly there and marked=
=20
up, it could be processed immediately by standard tools of both desktops, a=
nd=20
it can go into things like the translation workflow immediately.  I can't=20
think of any disadvantages - enighten me if there are some.

This could be done very easily and very quickly, by breaking out the files=
=20
this way:

* One gnome-index.docbook using Gnome's normal customization layer to OASIS=
=20
DocBook
* One kde-index.docbook using KDE's normal customization layer to OASIS=20
DocBook [1]
* One file per section in the HIG (name it something like <section>.docbook=
). =20
* Include those sections that are agreed upon by both parties directly into=
=20
both documents (this is as simple as defining a single entity, and then=20
including that entity in the index.docbook files)
* Optionally, up to two extra files per section in the HIG (named something=
=20
like gnome-<section>.docbook and kde-<section>.docbook) holding content tha=
t=20
is either not applicable to the other desktop, or cannot be agreed upon. =20
Each index.docbook above would include the appropriate content.

Then we could attack in two ways.  Either=20
1: Initially, all the sections could be of status "undiscussed", which woul=
d=20
give immediately a complete HIG document, but with much of the content=20
potentially subject to change.  Then work through it in some kind of order.=
=20
or
2: Each section is added as it is agreed upon here and finalised.

I'm partial to option 2.  I think that there is a fair amount of content th=
at=20
could be put to use immediately.  I also think it would keep clear separati=
on=20
between what is done, and what is not (there can always be placeholders=20
saying: "This section not finalised, see <link to GNOME HIG> and <link to K=
DE=20
UI guide> in the meantime" if it's deemed necessary.=20

I think given a concrete framework that we could release in very short orde=
r=20
with a whizz bang "Look what we've already managed to do" would be=20
encouraging all around, and give this project credibility, and maintain=20
interest.

I could do this in a couple of hours, given the existing GNOME sources, and=
=20
somewhere (xdg cvs?) to put the result, and I'm offering. =20

[1] Yes, we could probably maintain a single index.docbook wrapper, and use=
=20
PI's and role attributes to get DE appropriate results.  That would take me=
=20
something more than a couple of hours to get done as it would likely requir=
e=20
writing a whole lot of xsl for both KDE and GNOME to deal with it, and is=20
something to perhaps work toward at a future date.  In the meantime, I'm wi=
th=20
Aaron - lets dive in, and lets get some concrete work done.

Regards,
=2D-=20
Lauri Watts
KDE Documentation: http://i18n.kde.org/doc/
KDE on FreeBSD: http://freebsd.kde.org/
--Boundary-02=_ohQQ+O04PCvMY34
Content-Type: application/pgp-signature
Content-Description: signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (FreeBSD)

iD8DBQA+QQho/gUyA7PWnacRAgtQAJ9sB9IhqC3pT9xYE9Hz6C5G6lubYwCgkCcM
kqXGzihcidN13aFaEfXrYuY=
=9KFN
-----END PGP SIGNATURE-----

--Boundary-02=_ohQQ+O04PCvMY34--



-- 
open-hci mailing list
[email protected]
https://listman.redhat.com/mailman/listinfo/open-hci