Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki

[Ben de Groot]

On 4 April 2010 21:33, Joshua Saddler <nightmorph@g.o> wrote:
> Having to write a custom stylesheet just to get one wiki page to do what you want is pretty dumb.

Yes it would be. The idea is that you design consistent styling from
the get-go, so your stylesheets will be ready for those needs. Pretty
much the same as the current documentation solution.

> How is it unfair? Because tables really are so much simpler to write in GuideXML?

No, because they were displaying different things, using different features.

> Here's a more complicated table:
>
> http://www.gentoo.org/doc/en/xml-guide.xml#doc_chap2_sect10
> source: http://www.gentoo.org/doc/en/xml-guide.xml?passthru=1

And you think that's intuitive? Tables are a bitch, and I think both
the GuideXML approach (copied from HTML) and the wiki syntax one are
equally unintuitive. In my opinion reStructuredText is offering a
better alternative:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables

> Mediawiki mostly involves memorizing how many quote or tick marks you use.

The beauty is: you don't have to memorize it, as it is just a click of
a button on the editor interface away.

> This markup is *completely nonsemantic*. In GuideXML, you know EXACTLY what each tag means.

No, I don't. The body and title tags are used quite differently from
HTML, which is confusing. When do I use section and when do I use
body? And what the frak is stmt? And why uri and figure instead of
HTML's a and img tags? Except to a few dedicated people, GuideXML is
confusing.

> At any time, you can throw in HTML and CSS to do stuff, because apparently Mediawiki isn't flexible enough on its own to generate your desired rendering.

Rather, it's so flexible that it even accomodates using HTML and CSS
should you wish so. But you don't have to.

> Having to mix HTML with a totally different wiki syntax is stupid.

Having to mix HTML with a different dialect of XML is equally stupid,
and moreover it is confusing. At least with MediaWiki, you don't have
to use it, as there are other options.

> Having to learn CSS *on top* of learning wiki syntax (and HTML) just to write a document is retarded.

Wiki editors will not have to learn CSS, unless you have very specific
needs that are unforeseen by the designers of the stylesheets you use.

> You've tried to make the case that learning GuideXML is too hard, but in order to use Mediawiki you'd need to learn at least 3 languages.

You don't need to at all. Depending on how the maintainer configures
things, at most one markup language should be enough. And that is
greatly helped by the editor UI. So for most simple edits you don't
need to learn any markup language at all.

> [...] Leave the styling to a separate stylesheet, and let the code just be code.

Yes, that's the whole idea. It's just that MediaWiki offers the
flexibility to use those extra features, but you don't have to use
them.

> But that's at the price of standardization: since arbitrary tags and markup is allowed, there's nothing to keep consistency between documents, or even within the same document.

That's a matter of configuration. I'm all for locking that down and
use a consistent standard styling, so only relatively simple markup is
needed. (But we'd have the flexibility to do something more complex
should we wish to configure things so.)

> GuideXML at least has a clean, consistent visual representation. Once you start allowing arbitrary markup, there'll be a million and one ways of representing the same thing, and that's not good for someone trying to wade through documents. There *should* be a standard way of representing information.

I absolutely agree. And you can achieve the same with a wiki.

>> And if you really wanted to, you could easily write an extension to
>> parse GuideXML, so it could be used as wiki markup. So again, the
>> markup is not really an argument against using a wiki instead of our
>> current GuideXML+gorg setup.
>
> Except I haven't seen Mediawiki offer anything like our textual color palette or other code syntax and block-level formatting flexibility.

What do you mean? You can predefine styles in your CSS to express your
"textual color palette" (if I understand correctly what you meant by
that). There is advanced code syntax highlighting available, for
example using GeSHi.

>> 2. It is a non-transferable skill. You can't use it anywhere else.
>>    And unless you are a regular GuideXML writer, you will have to
>>    look up its particular usage almost every time you do use it.
>
> It's just XML. That's all. If you can write HTML, then you can write XML. XML is *easier*. It's got far fewer tags, for starters. That means much, much less to learn.

That's not fully correct. XML has in principle a practically infinite
number of tags. It all depends on which "dialect" you use. If it is a
dialect you do not use a lot, you will forget the usage of particular
tags.

> Oh, and guess what? You ebuild writers are already using XML every single time you make changes to ebuilds: metadata.xml, etc.

Yes, and I find that often I have to look up the specific usage of
anything beyond the standard minimal set of tags.

> Most of us have used GuideXML at some point or another in our /proj/ webpages and devspaces, if not in /doc/en/. Guess what? That's the same XML, and there's much, much more content constantly written for /proj/ and dev.g.o than for /doc/. So don't try to tell me that people don't have at least passing familiarity with it.

That's not the point. The problem is that most of us don't use it
often enough to be sufficiently fluent in it, and you will never use
it for anything else but gentoo.org pages. Moreover, there is no web
UI for quick edits, with helpful buttons and hints...

-- 
Ben de Groot
Gentoo Linux Qt project lead developer