Mailinglist Archive: opensuse-doc (66 mails)

< Previous Next >
Re: [opensuse-doc] Please make Lessons for Lizards Easier format (not XML)
  • From: Thomas Schraitle <thomas.schraitle@xxxxxxx>
  • Date: Mon, 1 Jan 2007 14:44:52 +0100
  • Message-id: <200701011444.53562.thomas.schraitle@xxxxxxx>
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@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
List Navigation
Follow Ups