[gentoo-dev] GuideXML editor, tidyGuide and Google SoC

[gentoo-dev] GuideXML editor, tidyGuide and Google SoC

[achumakov]

Hi devs,

I've recently (too late ;-) read that we (Chris White?) had proposed the
GuideXML
editor project for GSoC. I have some ideas to describe here, and (possibly)
willing to act as a co-mentor for this challenge.

It is interesting that we've already approached this task at Russian
doc translation project (as entire Gentoo is suffering from the lack of such
tools):

We had to choose the basic platform for wysiwyg editing (among some
existing tools), and had thought of the following:

1. The doc editor should be as similar to a regular word processor, as
possible.
2. It should have some spell checking tools included.
3. It should be internationalized.
4. There should be a bunch of compatible editors not to be ever stuck on
single tool.
5. Gentoo project itself is not much about wysisyg editing tool, so we
shoudn't
do it from scratch.

Hopefully, we've found many of open and closed source tools that can
accopplish this task.
Here's some of them we think suitable, all can be easily adapted to GuideXML
by templates:

1. OpenOffice.org (xslt)
2. Vex (css)
3. Serna (xslt)
4. XMLmind (custom)
(I think this list is still very incomplete)

The main problem is completely different (as we could see):
all the WYSIWYG tools seem to break initial internal document format making
it completely
unusable for CVS storage and DIFF (although we could switch to XML diff, I
don't really think
it's yet reasonable for next 1-2 years).


So, we have proposed to split the entire task into these two:

Step A.
Make a 'TidyGuide' XSLT that can format (or restore format of) any valid
GuideXML document
after processing by WYSIWYG editor, and just before commit.

XSL was chosen as a platform-independent technology (you can apply it on
file save in almost any
editor, or even in CVS itself).

This way, we overcome the main problem of existing WYSIWYG editors.

Step B.
Prepate templates for any editors you like -- there is no problem as we
haven't to deal with
internal formatting anymore.



So, although this effort was actually started within Russian Documentation
Project (unfinished yet),
I think it makes sense to bring it to Gentoo mainstream.

You can look at current projects' repo at
https://svn.shadanakar.org/rugentoo/ru/guidexml/
(comments to code are still in Russian, but the code itself is
self-descriptive)

Screenshots of WYSIWYG GuideXML in Serna and XMLMind are available at 
http://www.chumakov.ru/gentoo/technology/xml-editors.html (in Russian, too,
but not a problem
as the pictures are self-descriptive, too),
those for vex project--at
https://confluence.concord.org/display/CCTR/Gentoo+GuideXML+with+Vex


If it's interesting, I could convert all these comments into English (and
translate existing TidyGuide
software requirements specification, too) and contrubute all that code to
Gentoo in a couple of days.

So, what do you think about all this? Is is interesting enough? Could I
become a co-mentor for GuideXML
wysiwyg project?


--
Alexey Chumakov
Gentoo Russian Documentation Lead
achumakov@gentoo.org

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] GuideXML editor, tidyGuide and Google SoC

[Josh Saddler]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

achumakov@gentoo.org wrote:
> (snipped)

Templates seem a bit . . . hackish. Mostly we also need documentation writers to
be/who are comfortable with working with the XML code itself, tags and all.
WYSIWYG editors just don't strike me as a good idea for working on docs. Plus
someone would have to make extensions to it every time another feature or three
is added to GuideXML, like neysx's recent code highlights.

As long as users can use a plain text editor (gedit, leafpad, mousepad,
bluefish, etc.), all they have to do (besides validating it with xmllint before
committing) is run it through YosWink's repodoc [1], a thorough GuideXML QA checker.

No need for big heavy editors like OOo and lots of extra plugins/templates/etc. :)

Still, if this gets off the ground, I'll give it a test drive. I'm not big on
WYSIWYG, but I'll try it out.


[1] http://dev.gentoo.org/~yoswink/repodoc/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)

iD8DBQFEXweNrsJQqN81j74RAmIJAKCh8FszH/oS6te/zqx6r6VKe/jZkwCgjqf6
7/yff4TyaFZagHMD4dfK8g4=
=e5Pk
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

RE: [gentoo-dev] GuideXML editor, tidyGuide and Google SoC

[achumakov]

 

> jackdark@gmail.com wrote:
> achumakov@gentoo.org wrote:
> > (snipped)
> 
> Templates seem a bit . . . hackish. Mostly we also need 
> documentation writers to be/who are comfortable with working 
> with the XML code itself, tags and all.

First of all, we need _documentation_ and _documentation writers, don't we?


> WYSIWYG editors just don't strike me as a good idea for 
> working on docs. Plus someone would have to make extensions 
> to it every time another feature or three is added to 
> GuideXML, like neysx's recent code highlights.
> 

So, the template is the way: any good XML editor with a template 
behaves well when the doc doesn't fit template: it just switches to 
raw mode ;-)

Afaicr, making extension to 100-200 lines of template is still 
far easier than patching a brand-new WYSIWYG editor, too.

> As long as users can use a plain text editor (gedit, leafpad, 
> mousepad, bluefish, etc.), all they have to do (besides 
> validating it with xmllint before
> committing) is run it through YosWink's repodoc [1], a 
> thorough GuideXML QA checker.

How 'bout "Gentoo is about choice"?

> 
> No need for big heavy editors like OOo and lots of extra 
> plugins/templates/etc. :)
> 

OOo etc could make editing more productive for those not familiar
with XML odds - just imagine why translation of Gentoo doc is
so slow and weak?

> Still, if this gets off the ground, I'll give it a test 
> drive. I'm not big on WYSIWYG, but I'll try it out.

Thank you anyway.

--achumakov

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] GuideXML editor, tidyGuide and Google SoC

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 465 bytes --]

achumakov@gentoo.org wrote:
> OOo etc could make editing more productive for those not familiar
> with XML odds - just imagine why translation of Gentoo doc is
> so slow and weak?

Because you basically have to do everything yourself. Yup, you get some
contributions from your users, but those are of varying quality. I
haven't received any contribution that didn't require at least minor
tweaking so far.

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 258 bytes --]