Hi Alexey, happy new year! :-)
On Monday 01 January 2007 00:47, Alexey Eremenko wrote: > > I would like to tell you that starting contributing to LfL is very > difficult. Mainly because there are no user-friendly editors. I will cover that in a different mail. > I would like to request to move to easier format. > Either HTML, or plain text will do. (Maybe OpenDocument) > working with XML is EXTREMELY difficult. Did you try it? What do you think is difficult? Which problems occured? Rebecca wrote already a very good mail to your questions but let me answer to your suggestions in more technical detail: * Text As noted in previous post on opensuse-doc and on our Wiki pages it is always possible to write in simple text. Somebody have to convert it to a higher degree of semantics, in our case DocBook. This task have to be done one time. * OpenDocument Although you can write in this XML format manually I wouldn't consider it as a good alternative. From my perspective, it's even worse than DocBook. It is more of an exchange format. The specification of this format is *very large* (>600 pages!!). I don't think someone would write documentation for LfL in this format manually. This is not an alternative. * HTML Everybody who created web pages manually knows of HTML. It is well known, easy and you can see the results of your efforts instantly. However, it is not very good in carrying semantics, because it was never invented for this purpose. You can not know if a <b> tag contains an ISBN number or something else. You loose context. Unfortunatly, HTML can be very ambigious when you forget an end tag. Another drawback is you can not really convert it into other formats. Sure, there are lot of converters from HTML to text or something else but PDF? In the past I tried several converters for creating good looking PDF. Forget it, they have all their disadvantages. * DocBook XML This is our solution what we prefer. Remember, we are not alone: There are lots of different projects (KDE, GNOME, Subversion,...) who use DocBook as their main format. Why do they? Lets compare XHTML and DocBook: XHTML 1.0 Strict has 77 elements (if I counted correctly), DocBook version 4.5 appr. 400. This seems a bit overwhelming at a first glance. However, you *don't* need *all* elements. In general and from my experience you don't need more than 60-80 which is roughly the same size than (X)HTML. If you can handle (X)HTML then it should be also possible to write in DocBook XML. (X)HTML is not easier than DocBook. I think it's more a psychological barrier; after you get used to it you won't miss it. ;) For this reason, we created a kind of "template" of users who are not very familiar with DocBook. See [1]. You can use this file as a start and fill in your text/paragraphs. With time you grow with DocBook and get more experience with it. :-) Well, you may think "But tell me, why should I write in DocBook?". Let me emphasis the following advantages (read more from Eric Raymonds in "DocBook Demystification HOWTO"[2]): 1. Wikis have their advantages (simplicity,...) but they have a lack of higher semantics. For example, they can not distinguish a filename from a directory. With DocBook this is possible, if you want. This can be useful if you want to search for filenames but don't want include directories. (I know it seems as an artifical example, but we had in the past lots of these things needs.) 2. You can transform DocBook into several other formats, like (X)HTML, HTMLHelp, Manpages, WordML, XSL-FO, JavaHelp, EclipseHelp, OpenDocument and probably many others. Write once, publish everywhere. Isn't it an advantage that you just have to know and write ONE format and transform it to MANY others? Try to do it with a Wiki... 3. With DocBook you just have to care with your *text*, layout is a second priority. You concentrate on your text, convert it into your target format and *then* view it. It's the same with LaTeX. I know from my fellow students when they had to write their lab reports: They concentrated on the appearance, make it bold here, applied italic there did all kinds of "make it look good", but forgot the most important thing: their text. 4. You can validate DocBook files to let you correct it. 5. Probably other advantages that I missed due to new years day. ;-) Don't get me wrong, I don't want to bash Wikis. They have advantages and I like it too. However, you run into lots of technical troubles if you need to support additional formats, not only HTML. To simplify using DocBook, I would recommend the following handling with DocBook XML: 1. Download the template file[1]. 2. Write your text in paragraphs (use <para>...</para>, roughly the same that you would use in (X)HTML with <p>...</p>.) 3. Validate your file with our XML build mechanics. 4. Be proud of what you achieved so far. :-) 5. Improve your text, if neccessary, with additional tags. Use the reference page[3] from the book "DocBook -- The Definitive Guide" or ask on opensuse-doc for help. I know, it takes time and DocBook might have a steep learning curve. But it is worth the price. Let me know if you have additional comments, questions or concerns. :-) Best wishes, Tom ------------ [1] https://forgesvn1.novell.com/svn/lfl/trunk/common/xml/topic-template.xml [2] http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/index.html [3] http://www.docbook.org/tdg/en/html/part2.html -- ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Documentation Team Maxfeldstrasse 5 /\\ Technical Editor 90409 Nuernberg, Germany _\_v http://en.opensuse.org/Documentation_Team --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
