First, let me apologize if my posts are coming off as edgy. I just feel like I've been repainting the Hindenburg for the last four years. I've been trying very hard to create good user documentation within our current setup, and nothing seems to be working. I'm tired, and I want to finish this.
On Wed, 2006-07-12 at 06:03 +0200, Karl Eichwalder wrote: > Shaun McCance <[EMAIL PROTECTED]> writes: > > > Why not just give all the elements simple and consistent names > > to begin with? Nobody can even remember the DocBook elements, > > so what's the point of catering to that experience? > > The good thing about DocBook is, that it is by now an accepted standard > in the free software and open source community. Many developers and > writers are sufficiently enough familiar with the DocBook markup. Even > if some element names are weird, it might make sense to keep them > because we have learnt them (and beginners can learn them as well > without too much trouble). My experience is that very few of these people are joining the Gnome documentation effort. They're off writing largely geeky docs (witness the sorts of docs the excellent Fedora documentation squad usually produces). By and large, when we do actually have people who want to contribute to Gnome documentation, they are not seasoned *Nix documentation folks. They don't know DocBook, they don't know TeX, and they certainly don't know roff. > Yes, I'm quite conservative. I'd say we should wait another 10 years > before start to push the next DTD/Schema onto the community. ATM, the > problem is not the markup per se, but the lack of a free XML editor. We > need a combination of oxygen and emacs (psgml/nxml/xml). If I'm still the Yelp maintainer in 10 years, somebody please have me committed to an asylum. I completely agree that the lack of a free XML editor is a serious hindrance to our ability to recruit quality tech writers. I've seen various people try to address this, and one thing that always causes problems is that DocBook is hard. Making pretty buttons for all the inline markup doesn't change the fact that you have too much inline markup. Now you just have a cluttered user interface. As for new formats and sticking with the old, I figure DocBook 4 has about three solid years of life left, and then another two years or so of a slow and agonizing death. Anybody sill using DocBook will switch to DocBook 5. DocBook 5 is a fairly fundamental departure from DocBook 4. It shares many of the same markup elements, to be sure. But there are radical changes in ways that will have huge impacts on folks like me that write tools. We will have to invest time into a transition within the next few years either way. I would really rather spend that time transitioning to something that can really fulfill our needs. > > As for existing tools, no existing tool is going to get the > > link mapping correct. You might get some formatting fluff > > for free, but that sort of stuff is labor cheap compared to > > the rest of the work involved. > > There is some truth about your statement. But do not forget that > people have written keyboard macros and editor extensions to make > DocBook editing less cumbersome. There are also DocBook converters. So > more tools exist than just formatting tools. This is all true. My general experience with DocBook tools is that none of them go all the way. My HTML converters, for example, are not fully conforming. The "standard" ones, on the other hand, are obtuse and painfully slow. The DocBook PDF tool chains I've seen aren't very spectacular, often due to the fact that XSL-FO processors aren't very good. This is perhaps a good time to point out that I consider the documentation system to be a core part of our platform offering. As such, I take backwards compatibility very seriously. DocBook will continue to be a supported option for documentation for the foreseeable future. > Yeah, DITA is complex... but it is topic oriented. > > > People seem to think that this is nothing more than simpler > > DocBook. It's not. It has nothing to do with DocBook, and > > there's no reason to pretend it does. I should call it MIND: > > MIND Is Not DocBook. > > ;) I still believe that DooBook is good enough. If you want "topics" > use unnumbered section elements; if special link tags are actually > missing, import them using namespaces. I've tried for years to make it good enough, and I just don't think it ever will be. Not for what I'm trying to accomplish. Maybe I'm wrong. I'm not removing DocBook support from Yelp, and I'm not strong-arming anybody. I rarely use my purported power to force anything. Writers are ultimately free to tell me I'm off my rocker. -- Shaun _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
