I have an idea: make openSUSE wiki available offline -- that is -- instllable via rpm, that will automatically start mediawiki and apache on offline PC. This way it will be easy to read (and write !) documentation even when offline, and simply upload it later. That is - make FULL integration between offline SUSE wiki and Online one. -Alexey. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Alexey Eremenko wrote:

working with XML is EXTREMELY difficult.

No. Yes (I like such "réponse de Normand" as we say in France :-) No it's not difficult. starting from a template allow anybody to write docs in a manner of minutes. look at: http://tldp.org/LDP/LDP-Author-Guide/html/index.html for a similar situation. Yes, if not difficult, it's tedious for casual use. Like the wiki page for edits and comments, we could use a wiki page (openSUSE?) for drafts. In fact SDB pages are very near from that. of course, at some moment, somebody will have to make it xml :-( some years ago I worked to make available a docbook editor in OpenOffice, there is something like this, I don't know a what point it's usable (I gave up far before it become live) a docbook plugin for openoffice would be of major interest, not only for us, but evidently it's not obvious (if any kind of syntax checking is to be done) be aware that an wml editor is similar to an html editor and no html editor is really usable by non technical people if you want a clean code (that is a code exchangeable between html editors) I always turned back to vi after using bluefish, quanta+, mozilla or NVu (not to mention Front page or dreamweaver that I feeled like nightmareweaver) jdd -- http://www.dodin.net http://dodin.org/mediawiki/index.php/GPS_Lowrance_GO --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Hi, On Monday 01 January 2007 17:40, jdd wrote:

Thomas Schraitle wrote:

...

3. With DocBook you just have to care with your *text*, layout is a second priority.

let me enphasis on this. this is not docbook related.

Yes, if you look at the complete picture. However, I meant it in comparision to (X)HTML. :)

[...] the main value of docbook is the number of backend allowing translation to virtually anything available...

In my humble opinion this is an advantage that is highly underestimated! (X)HTML is good, but it's /not/ the solution to everything, nor Wikis. Nor is it DocBook. Use the right tool for the right task. However, for documentation that has to be available in different formats, the solution is in most cases DocBook. It's a defacto standard (there is also DITA but that's a different story.) I don't know of anything better. Both, DocBook and the DocBook stylesheets, form a tool set; they are open, mature, well written and simple to customize. :) In former times our documentation was written in LaTeX. It worked somehow but the HTML output always suffered. With DocBook plus the DocBook stylesheets we don't have these problems anymore. Best wishes, Tom -- ---------------------------------------------------------------------- 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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org