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

[Joshua Saddler <nightmorph@gentoo.org>]

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

On Sun, 4 Apr 2010 17:23:54 +0200
Ben de Groot <yngwin@gentoo.org> wrote:

> As has been pointed out, your table example was unfair, as they don't
> do the same thing. I would frown on such inline styling (that's what
> stylesheets are for), and there are a number of ways you can markup
> tables in wikis. One is to allow HTML tags, so it would be very much
> like GuideXML. Another one, which I prefer personally, is to use
> reStructuredText, which is even clearer than HTML markup.

Having to write a custom stylesheet just to get one wiki page to do what you want is pretty dumb.

How is it unfair? Because tables really are so much simpler to write in GuideXML? 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

> > By moving to a wiki, you'll lose a huge percentage of what GuideXML can do,
> 
> I don't see that at all. Is there any essential feature of GuideXML
> that is missing in MediaWiki? (Let's take that wiki implementation as
> the most likely one we will adopt.) I haven't seen anything yet that
> is impossible or very difficult to do. Do you really think that
> GuideXML is so special and advanced that nobody else had the same
> needs and that major wiki engines do not provide in those needs?

Mediawiki mostly involves memorizing how many quote or tick marks you use. This markup is *completely nonsemantic*. In GuideXML, you know EXACTLY what each tag means. It's semantic. <ul> starts an unordered list. <ol> starts an ordered list. <li> is a list item. <b> for bold text. <e> for emphasized text, similar to XHTML's <em> tag. <table> to start a table.

Mediawiki requires you to memorize numbers of marks to achieve the same effect: two ' ' for italic text, three ' ' ' for bold, five ' ' ' ' '  for bold AND italic.

Now take a look at the section on Mediawiki lists: whitespace becomes part of your formatting. Lame. At least with GuideXML, you can use whatever whitespace or linebreaks you want to keep code human-readable, and know that it won't affect the rendered version.

Oh, *and* you have to prefix Mediawiki list items with ; and : , which is completely nonsensical and arbitrary. The character doesn't explain what it's for, unlike semantic XML tags.

Take a good look at the Mediawiki "mixture of lists" sample:
(I'd provide a direct link, but there's no built-in way to snap to it)
http://www.mediawiki.org/wiki/Help:Formatting

That is just plain ugly. The eye has a hard time unjumbling the ##s and ;:* crammed together. Also, note another flaw of Mediawiki:

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. Having to mix HTML with a totally different wiki syntax is stupid. Having to learn CSS *on top* of learning wiki syntax (and HTML) just to write a document is retarded.

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.

In my earlier email, I shared a code sample of GuideXML tabls. Mediawiki's idea of tables?

{| to start. |+ for a caption. |- for a row. ! for headers, and | for data. Use more || symbols for more rows.

Seriously, what part of this is easily understood to be table markup?

*And* you can mash in XHTML attributes to style the text. Big no-no. Leave the styling to a separate stylesheet, and let the code just be code.

Yeah, since Mediawiki tables can accept straight-up CSS (another skill you had all better learn if you're going to write valid code, apparently), you *can* do a bit more color formatting than with our existing XSL rules for GuideXML. I'll grant you that.

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. 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.

> 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.

> 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.

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

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.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]