Please make Lessons for Lizards Easier format (not XML)

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Please make Lessons for Lizards Easier format (not XML)

Alexey Eromenko
Hi all !

I would like to tell you that starting contributing to LfL is very difficult.
Mainly because there are no user-friendly editors.

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.

-Alexey.
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Please make Lessons for Lizards Easier format (not XML)

Alexey Eromenko
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Please make Lessons for Lizards Easier format (not XML)

Rebecca Walter
In reply to this post by Alexey Eromenko
On Monday 01 January 2007 00:47, Alexey Eremenko wrote:
> Hi all !
>
> I would like to tell you that starting contributing to LfL is very
> difficult. Mainly because there are no user-friendly editors.
>
> 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.


Toms can fill us in on the editor situation.  I think there is one some people
in-house use, but it may require a license. I really don't know.  I only ever
use emacs. I know that they have experimented with different options, but
several of us stuck to vi and emacs.

The problem is that the formats you suggest don't result in the quality or
number of output types really needed for this project.

You can contribute plain text documents and have someone else convert it to
XML for you.  It is quite possible. I don't know if we have an exact workflow
planned yet, but my guess is that you can check a text file into SVN and send
out a mail asking for conversion.

Also XML is very much like HTML in how the markup works.  The tags are just a
bit different.  It is a very common way of making books.  It really isn't
that hard to learn and it makes it much easier than other formats for getting
a unified appearance and a usable finished document.

I'm sorry you find contributing so difficult.
Sincerely,
Rebecca


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Please make Lessons for Lizards Easier format (not XML)

Thomas Schraitle-2
In reply to this post by Alexey Eromenko
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Please make Lessons for Lizards Easier format (not XML)

jdd@dodin.org
In reply to this post by Alexey Eromenko
Alexey Eremenko wrote:

> 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.

mediawiki makes available snapshots of it's wiki, we could
do the same. I don't really know if it's easy or even usefull.


installing mediawiki locally is not so easy and not usefull
at all for a static site, better have an html copy if necessary.

may be giving users a (monthly?) html copy of openSUSE wiki
could be better than waiting users to use wget to do so?

is all that at all necessary??

jdd

--
http://www.dodin.net
http://dodin.org/mediawiki/index.php/GPS_Lowrance_GO
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Please make Lessons for Lizards Easier format (not XML)

jdd@dodin.org
In reply to this post by Alexey Eromenko
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Please make Lessons for Lizards Easier format (not XML)

jdd@dodin.org
In reply to this post by Thomas Schraitle-2
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.

any document that needs emphasis on the layout should
probably be rewritten. TeX, for example, makes it very
difficult to know where a figure will be on the final book,
but this figure will be very easy to find.

most writers enphasis on layout because they don't know
there are better tools. Even MSword can be used to have very
structured documents, but most users makes terrific work
with it (if not the translation to openoffice would be done
in a snap).

think your document will be used by "normal" users and
"disabled" ones, for example visually impaired.

You make a big bold red text. how will the impaired use
this? think about it. observe that what you want is _not_ a
red bold, but to make this text more visible than the rest.
so the html tag "em" (for emphasis). any backend can
translated this "em" in red bold on screen, italic bold on
black print and on mâle voice on a speach syntetiser.

all this just as example, of course.

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

jdd

--
http://www.dodin.net
http://dodin.org/mediawiki/index.php/GPS_Lowrance_GO
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Please make Lessons for Lizards Easier format (not XML)

Thomas Schraitle-2
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Please make Lessons for Lizards Easier format (not XML)

Berthold Gunreben
In reply to this post by jdd@dodin.org
On Mon, 1 Jan 2007, jdd wrote:
 
> 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)

I just added a README how I use vi to edit xml. Maybe you can give me
some hints how to improve that further ...

https://forgesvn1.novell.com/svn/lfl/trunk/contrib/xml-editors/vim/README

Thanks

Berthold

--
------------------------------------------------------------------
 Berthold Gunreben               SUSE Linux GmbH -- Dokumentation
 mailto:[hidden email]                                  Maxfeldstr. 5
 http://www.suse.de/                   D-90409 Nuernberg, Germany
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]