On Fri, 2006-07-07 at 14:19 +0200, karderio wrote: > Hi :o) > > On Wed, 2006-07-05 at 17:14 -0500, Shaun McCance wrote: > > On Wed, 2006-07-05 at 23:02 +0100, Joachim Noreiko wrote: > > > --- karderio <[EMAIL PROTECTED]> wrote: > > > > Well, this seems somewhat similar to what we had > > > > already : an index that > > > > writers would add the content to, except that > > > > currently we don't have > > > > the actual index, but a new index that represents > > > > how things should be > > > > after reorganisation (at least that is the theory, I > > > > suppose). > > > > > > Yeah... > > > the Desktop User Guide is such a monster of a thing > > > that it hurts my head to think of having two copies of > > > it on the wiki AND cvs. > > > (An aside to Shaun if he reads this: Project Mallard! > > > we need to dice the monster up into topic-sized > > > chunks!) > > > > Yelp infrastructure should be in place within the next > > three months. Once the 2.16 docs are out, I'd like to > > get any interested documentation writers to sit down > > with me and actually write some documentation in the > > new format, as we develop it. > > > > I think you'll find the format pleasantly simple, but > > it will require you to think differently about content > > organization. Fortunately (and unlike linear documents) > > content really can be written before we've made all the > > organizational decisions, and we can reorganize stuff > > with little to no impact on content. > > > > It is coming. I promise. > > Cool :) > > I must confess, I'm not sure exactly what this consists in, but the more > I understand it the cooler it seems :) > > Does this replace docbook as <i>the format</i> ? If so, may we as well > invest in working on the wiki, as online docbook editors may not be so > useful ?
It does replace DocBook as the format of choice. The format of choice will not be any sort of wiki syntax. The chances of me adding a parser to Yelp for ''text'' that '''looks''' like **this** are &--pretty--& [EMAIL PROTECTED]@$. The format is XML, as $DEITY intended. Here's what you get: 1) The pages you see in Yelp are exactly the pages you write. Yelp won't have to look at a deep section heirarchy and try to figure out the most logical way to present chunked information to the user. 2) The pages each stand on their own. They are not part of a linear structure. Instead, they are linked into nodes that help users navigate and find information. 3) There will be maybe 10-15 block-level elements, with very clear semantic purpose and with reasonably well-specified presentation. 4) There will be exactly one table model, and it will be the one you get with HTML. CALS tables kill kittens. 5) There will be maybe 10-15 inline elements, with very clear semantic purpose. You know how, in DocBook, you have to hunt through 50 or so inline elements, and then there are maybe five that sort of closely match what you're trying to mark up? Or you have to use systemitem because there's not a specific element for your needs, but then that feels dirty because there are *very* specific elements for other things. Let's stop the insanity. 6) The presentational behavior of all automatic text will be specified very very very exactly. It has a huge impact on how you write your document, and you deserve to know what a processor is going to do with your text. 7) The format is simple enough that sophisticated editors will not be difficult. Writing a wiki-esque thing to do online editing should be easy enough. If people really like that workflow, then we can work towards that. What I don't believe in is converting presentational markup to semantic markup. I don't think anything short of natural language parsers have any hope of getting the conversion right. 8) Documents are pluggable. I can't even begin to explain just how cool this one bullet point is. Now here's everybody's first chance to get in on the fun: The code name for the project-as-a-whole is Project Mallard. This is sort of an inside poke at DocBook. But Mallard is a dumb name for a help format. So everybody: NAME MY XML FORMAT! That's right. You can be forever immortalized by having named the XML format that will take over the desktop documentation world. A decade from now, an aspiring young technical writer will be learning this format in college, as it will then be the industry standard. And she'll be chatting with her professor, and her professor will say, "When I was your age, we didn't have $FORMAT. And we had to walk uphill in snow over broken glass to get to our text terminals to write documentation in DocBook. But that all changed when $PERSON galvanized the industry by naming $FORMAT." -- Shaun _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
