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

[Joshua Saddler]

On Mon, 5 Apr 2010 02:08:06 +0200
Ben de Groot <yngwin@g.o> wrote:

> 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

At least the GuideXML approach to tables is familiar to anyone who's worked with HTML. Oh wait, you shouldn't be comparing GuideXML with HTML. More on that later in this message.

Also, don't get me started on rST's many failings. It's just like wiki syntax, in that anything you want to do besides line spaces and lists involves stupid nonsemantic code. Having to define URIs twice is retarded:

"External hyperlinks sample sentence, like Python_."

.. _Python: http://www.python.org/ 


Tables:
A big problem with rST and wiki markup is that they try to preserve the rendered format within the source code view.

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+ 

That's rST source. This gets unwieldy very quickly for larger tables, as they'll overflow your editor window. Hey, that might not be a problem, but it's also a losing proposition to try to have that stuff rendered within the source view.

Let the renderer take care of the final rendering, as really, tags and markup are all arbitrary. What should matter is how it appears in your webbrowser, since that'll vary from the source view anyways.

. . . I hope you aren't seriously suggested rST as the wiki format.

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

And not everyone will want to do that. I certainly don't like clicking around when it's easier and faster for me to just type the code myself.

Really, you're mostly making a case for a graphical XML editor like Beacon, rather than making a case for a wiki. :)

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

That's your problem, then. Do you know what semantic means? Semantic doesn't mean "just like HTML." So stop treating it that way. Let's look at semantic tags.

It's not hard to see that <var> is a variable and that <stmt> is a statement, and <comment> is a comment. Semantic markup is markup that means what it says. Using punctuation marks like '  '' ; : is neither semantically useful nor easily readable, as I showed in the code samples you oh-so-casually skipped over. Nice try. ' and ' ' mean nothing in and of themselves.

But you're not a web author, so I'll stop trying to beat you over the head with how things work. Next point:

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

Why the hell do you keep bringing up HTML? Stop comparing GuideXML with HTML. Treat them as two separate languages, please.

I only mentioned GuideXML in the context of "it's easier to learn because it has fewer tags than HTML" -- you operate under the mistaken assumption that GuideXML should be *like* HTML, and that HTML has too many tags. You assume that everyone comes from an HTML background and thus will be confused by GuideXML.

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

Okay, then you also need a way to get those styles into your document by coming up with new tags or wiki markup.

<var> is a variable in GuideXML, and it'll be colored yellow. You mark this variable in a <pre> block with the <var> tag, which is created just for this purpose. How do you accomplish this in, say, Mediawiki syntax? Without trying to recycle some crap bit of HTML or tacking on inline styles.

Using <span> is ugly, because it's HTML. You should NEVER have to use more than one markup language at a time.

Do all the wikis out there have solutions for adding custom markup/tags?

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

By "XML" I mean GuideXML.

And yes, clearly GuideXML and metadata.xml are some of your weak areas if you have to keep looking up the basics. However, with practice you *will* get better. :)

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

And you'll never use wiki syntax for anything but wiki pages. Specifically, the syntax of whatever wiki is chosen, and not all wikis are equal, so there's no guarantee that your syntax will be useful elsewhere. What's your point?

Quick edits are edits that go right to the code, where you don't have to slow down by using anything but the keyboard. Work with web languages long enough, and you'll appreciate not being hampered by a GUI.