Gentoo Archives: gentoo-dev

From: Ben de Groot <yngwin@g.o>
To: gentoo-dev@l.g.o
Subject: Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki
Date: Mon, 05 Apr 2010 00:08:15
In Reply to: Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki by Joshua Saddler
1 On 4 April 2010 21:33, Joshua Saddler <nightmorph@g.o> wrote:
2 > Having to write a custom stylesheet just to get one wiki page to do what you want is pretty dumb.
4 Yes it would be. The idea is that you design consistent styling from
5 the get-go, so your stylesheets will be ready for those needs. Pretty
6 much the same as the current documentation solution.
8 > How is it unfair? Because tables really are so much simpler to write in GuideXML?
10 No, because they were displaying different things, using different features.
12 > Here's a more complicated table:
13 >
14 >
15 > source:
17 And you think that's intuitive? Tables are a bitch, and I think both
18 the GuideXML approach (copied from HTML) and the wiki syntax one are
19 equally unintuitive. In my opinion reStructuredText is offering a
20 better alternative:
23 > Mediawiki mostly involves memorizing how many quote or tick marks you use.
25 The beauty is: you don't have to memorize it, as it is just a click of
26 a button on the editor interface away.
28 > This markup is *completely nonsemantic*. In GuideXML, you know EXACTLY what each tag means.
30 No, I don't. The body and title tags are used quite differently from
31 HTML, which is confusing. When do I use section and when do I use
32 body? And what the frak is stmt? And why uri and figure instead of
33 HTML's a and img tags? Except to a few dedicated people, GuideXML is
34 confusing.
36 > 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.
38 Rather, it's so flexible that it even accomodates using HTML and CSS
39 should you wish so. But you don't have to.
41 > Having to mix HTML with a totally different wiki syntax is stupid.
43 Having to mix HTML with a different dialect of XML is equally stupid,
44 and moreover it is confusing. At least with MediaWiki, you don't have
45 to use it, as there are other options.
47 > Having to learn CSS *on top* of learning wiki syntax (and HTML) just to write a document is retarded.
49 Wiki editors will not have to learn CSS, unless you have very specific
50 needs that are unforeseen by the designers of the stylesheets you use.
52 > 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.
54 You don't need to at all. Depending on how the maintainer configures
55 things, at most one markup language should be enough. And that is
56 greatly helped by the editor UI. So for most simple edits you don't
57 need to learn any markup language at all.
59 > [...] Leave the styling to a separate stylesheet, and let the code just be code.
61 Yes, that's the whole idea. It's just that MediaWiki offers the
62 flexibility to use those extra features, but you don't have to use
63 them.
65 > 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.
67 That's a matter of configuration. I'm all for locking that down and
68 use a consistent standard styling, so only relatively simple markup is
69 needed. (But we'd have the flexibility to do something more complex
70 should we wish to configure things so.)
72 > 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.
74 I absolutely agree. And you can achieve the same with a wiki.
76 >> And if you really wanted to, you could easily write an extension to
77 >> parse GuideXML, so it could be used as wiki markup. So again, the
78 >> markup is not really an argument against using a wiki instead of our
79 >> current GuideXML+gorg setup.
80 >
81 > Except I haven't seen Mediawiki offer anything like our textual color palette or other code syntax and block-level formatting flexibility.
83 What do you mean? You can predefine styles in your CSS to express your
84 "textual color palette" (if I understand correctly what you meant by
85 that). There is advanced code syntax highlighting available, for
86 example using GeSHi.
88 >> 2. It is a non-transferable skill. You can't use it anywhere else.
89 >>    And unless you are a regular GuideXML writer, you will have to
90 >>    look up its particular usage almost every time you do use it.
91 >
92 > 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.
94 That's not fully correct. XML has in principle a practically infinite
95 number of tags. It all depends on which "dialect" you use. If it is a
96 dialect you do not use a lot, you will forget the usage of particular
97 tags.
99 > Oh, and guess what? You ebuild writers are already using XML every single time you make changes to ebuilds: metadata.xml, etc.
101 Yes, and I find that often I have to look up the specific usage of
102 anything beyond the standard minimal set of tags.
104 > 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.
106 That's not the point. The problem is that most of us don't use it
107 often enough to be sufficiently fluent in it, and you will never use
108 it for anything else but pages. Moreover, there is no web
109 UI for quick edits, with helpful buttons and hints...
111 --
112 Ben de Groot
113 Gentoo Linux Qt project lead developer


Subject Author
Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki Joshua Saddler <nightmorph@g.o>