Hi Alexey, On Monday 08 May 2006 19:41, Alexey Eremenko wrote:

I have heard that a new community tutorials are planned for SUSE Linux. I want to participate. Where can I find the links ?

I don't know of any links. Maybe others have more information. ;)

Second topic - I would like to add some of community's how-to's & Novell docs together - and have them installed *by default* on all new SUSE Linux setups.

Is there any realistic way to merge docs?

This could be difficult. We write our documentation[1] in Novdoc[2], a subset of the famous DocBook DTD. Writers who wants to participate have to deal with XML. This can sometimes be difficult. :) Another problem is to exchange XML and Wiki texts. If you go from XML to Wiki you loose lots of semantics. And from Wiki to XML this is also very problematic: it needs too much time if you want to convert it. Lots of manual intervention. At the moment it is more a "one-way-street" from Xml to Wiki. Tom ------ [1] http://forge.novell.com/modules/xfmod/project/?suselinux-docs [2] http://forge.novell.com/modules/xfmod/project/?novdoc -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Technical Editor Maxfeldstrasse 5 /\\ Documentation Team 90409 Nuernberg, Germany _\_v http://www.suse.com

Hi, On Tuesday 09 May 2006 14:36, jdd wrote:

Thomas Schraitle wrote:

...

[...] Writers who wants to participate have to deal with XML. This can sometimes be difficult. :)

good point :-). what are _you_ using? vi?

Depends on my mood: sometimes Emacs, sometimes oXygen. ;) The last was part of the XEP formatter. Both have their advantages (and disadvantages of course.)

...

[... exchange text in Wiki ...] At the moment it is more a "one-way-street" from Xml to Wiki.

xml is the official way to import/export to/from mediawiki.

Do you have a link at hand?

of course, xml is pretty what you want it to be :-), but an effort to make better import export modules for mediawiki could be a _very intersting_ thing for CoS, for example. and worldwide intersting. (sorry I'm completely unable to help in this)

Yes, it could be. But I doubt it would be more --- well lets say --- "accurate" than handmade XML. They play on different games. ;) How do you mark your text as "filename" if their is no equivalent in Mediawiki? Maybe I am wrong but I suppose the conversion is not the problem -- but the semantics are. Tom -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Technical Editor Maxfeldstrasse 5 /\\ Documentation Team 90409 Nuernberg, Germany _\_v http://www.suse.com

Thomas Schraitle wrote:

Do you have a link at hand? http://en.opensuse.org/Special:Export

:-) jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos

Hi Alexey, On Tuesday 09 May 2006 15:08, Alexey Eremenko wrote:

I vote for the standard HTML format. (and user-firendly programs are -- OpenOffice & NVU)

This is no option as we need to exchange our text with Novell.

Why should I write in XML ? I dunno that format and don't know any user-firendly program that writes XML docs.

Probably we misunderstood each other. You can still write your documents in the openSUSE wiki. However if you want to participate in the documentation that comes with SUSE Linux it would be very helpful for us to have it as XML.

Can OpenOffice & NVU make XML docs ?

OpenOffice saves its documents as packed XML but it is not the same as we use. About NVU I don't know, probably it's for HTML only. Tom -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Technical Editor Maxfeldstrasse 5 /\\ Documentation Team 90409 Nuernberg, Germany _\_v http://www.suse.com

On Tue, 9 May 2006, Alexey Eremenko wrote:

...

Can OpenOffice & NVU make XML docs ?

Well, I actually remember that OpenOffice 2 uses OpenDocument, and i'ts XML based - so yes - I can write in OpenDocument Format (ODF) and send it to Novell.

Will this be good enough for merging community's (my included) docs & Novell ?

no, because the DTD is different and the OOo XML would still need to be converted into valid NovDoc XML. But editors as kate for example can pull in a custom DTD and assist you in creating valid XML that works just fine. -- Jana Jaeger jjaeger@suse.de SUSE LINUX Products GmbH Documentation Maxfeldstr. 5 +49 (0) 911 74053-0 D-90409 Nuernberg http://www.suse.de

On Monday 08 May 2006 19:41, Alexey Eremenko wrote: Hi, [I have read the other answers to this thread, but I believe that you have been misunderstood]

I have heard that a new community tutorials are planned for SUSE Linux. I want to participate. Where can I find the links ?

I do not know of a special initiative that has been launched recently, but new tutorials (aka HowTos) get written frequently. See http://en.opensuse.org/Category:Howto for a list of existing HowTos (you need to scroll down a bit - the page layout is broken [I have fixed this loooooooooooong ago but unfortunately it didn't made the production system until now ;-((]). HowTos on opensuse.org are _not_ written in XML, but in HTML/wiki syntax ;).

Second topic - I would like to add some of community's how-to's & Novell docs together - and have them installed *by default* on all new SUSE Linux setups.

IMHO a larger part of the general Linux documentation (that can be found on http://tldp.org/) already is available in SUSE Linux - although not everything is installed by default. Along with this documentation the SUSE Linux manuals are also part of SUSE Linux (and are installed by default). Add a wish to http://en.opensuse.org/Feature_Wishlist in order to ask whether everything could get installed by default.

Is there any realistic way to merge docs?

I assume that you are referring to wiki documentation on opensuse.org and NovellForge when talking about "Novell docs". Personally, I do not think that it makes sense to put this on SUSE Linux, because these web pages constantly get changed (they are hosted on a wiki, after all). But you may, of course, add another wish to the package wishlist at: http://en.opensuse.org/Package_Wishlist -- Regards Frank Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.novell.com/ "Reality is always controlled by the people who are most insane" Dogbert

On Tuesday 09 May 2006 15:46, Alexey Eremenko wrote: Hi,

...

I assume that you are referring to wiki documentation on opensuse.org and NovellForge when talking about "Novell docs". Personally, I do not think that it makes sense to put this on SUSE Linux, because these web pages constantly get changed (they are hosted on a wiki, after all).

Regards Frank

Frank, The fact that documentation changes doesn't mean users must get the SUSE distro undocumented.

this is a very dangerous thing to say on a list the whole team that actually documents SUSE Linux is reading ;-)))

The fact that linux-kernel changes everyday doesn't mean that users get SUSE distro without the kernel either.

The *sole* purpose of distro - is to make it all available offline - that is - make *frozen* in time packages - both docs & software - available to general public in convenient way.

Have you ever tried to make an installable Linux system from packages you downloaded from various sources? Making a distro is much more than just packaging and burning a DVD ;-). Nevertheless, I think I see your point. You would like to have something like a "SUSE Linux cookbook" added to the documentation, correct? -- Regards Frank Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.novell.com/ "Reality is always controlled by the people who are most insane" Dogbert

Hi Alexey, Let me just comment on one part of your mail:

4) documentation devision - for different skill levels of users - that is for total noobs to computers tutorials, for Windows power-users, for newbie admins, for newbie programmers and for advanced programmers.

We already try to achieve that goal - though we may not have reached it fully yet - but you will find that the different manuals SUSE ships address different kinds of "target groups": for example, the Start-Up manual includes many chapters mainly for end users whereas the focus of the Reference manual is more on administrators. Also the other documentation included in the KDE Help Center, which bundles information from many different sources, is structured into categories: the table of contents shows categories such as "applications", "development" or "administration". Do you think that the differentiation of the texts is not detailed enough? Regards, Tanja -- ----------------------------------------------- Tanja Roth taroth@suse.de SUSE LINUX Products GmbH Documentation Maxfeldstr. 5 +49 (0) 911 74053-0 D-90409 Nuernberg http://www.suse.de

Alexey Eremenko wrote:

Actually what I want is difficult to achieve. I want:

to be in a perfect world :-) you need to join the http://tldp.org team. You will see how difficult it is. I don't know if the archives are all available, because I remember discissing how we could do a doc cd for the ldp and all the problems this was (we did). jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos

to jdd: Perhaps I will join TLDP. Most Linux "advanced" documentation is generic - that is - compatible with other Linux systems - Mandriva & Fedora & other LSB compatible distros. While most newbie stuff is SUSE specific - that is how to use KDE Desktop and Yast with screenshots. Anyways I have a good idea: I would like to write a guide "Introduction to Linux Command-Line" in a cross-distro manner, but with distro-specific plugins. A Slackware book might be modified. With SUSE specifics added. But how to implement the very new concept of plug-innable documentaion is still an open question. Also how will other people value that ?

jdd wrote: <snip>

only Yast is really SUSE generic, apart from a great amount of little config details :-) <snip>

Hi Jean, YaST is most prominent SUSE specific, but there is a lot of differences. Try to use generic Xorg X11 server with generic options. Hunting errors you'll see how different they are. There is a lot that should be mentioned in documentation that can be used by advanced users to improve packages, not in generic form, but in the SUSE specific way. That is part that should be added to Alexey list of specifications. Present is just for various levels of users, up to administering existing (given) system. IMHO nature of a lot of Linux users is to experiment, that is why they use something that is not main stream. Without spefications how to adjust source to play nice with the rest of the system, they are forced to reinvent the wheel, before any other action. BTW, as you mentioned before, there is a lot of work, and we'll do better to split it in small tasks. For instance providing standard SUSE documentation in wiki form would be one task that can help to activate many users to start adding, editing, asking questions. Discussion pages can be used for what they are meant to be. HOWTOs maintained on tdlp.org are free and could be used as a seed for more SUSE specific articles. That will benefit us and them as they can include opensuse.org articles to make HOWTOs more usable in the way they are ment to be, not generic explanation, but practical tip for everyday problems. Now back to square one. We have to rethink the opensuse.org structure, vote and do as agreed. Guys from documentatio team have huge experince in structuring books ie. chapters and indexes, and can give initial idea how to organize namespace tree from documetation node (page) further. -- Regards, Rajko.

Hi, On Tuesday 09 May 2006 18:58, jdd wrote:

Thomas Schraitle wrote:

...

Thanks! I tried it with the documentation page of the openSUSE wiki.

But ... the problem is still the same. :-( It is just a nice wrapper around the original text filled with some metainformation. No semantics.

what I said is that "xml" is nor the problem nor the solution. nowaday anybody do xml. however xml is a very good thing as langage is :-)

Ok, I see your point. However to make it clearer: XML becomes only useful, if the *contents* in your document are also marked up reasonably. We have an XSLT stylesheet that prints out all links. With another script it checks if these links are still accessible. So it's a kind of "qualitfy check". It would be not possible, if we (as writers) don't markup it accordingly. And this is the crucial point: XML is (only?) useful, if you investigate some time in your markup. To write documents in XML can be sometimes awkward for unexperienced users. But if you get used to it it is pretty easy. ;)

[...] on the contrary it's easy to go from any docbook/novbook/ structured form to html. The result will certainly lose part of the markup though.

Yes, that's the nature of this approach. :)

anyway, all this is _text_ and scripts can be made like sgmltools and linuxdoc to have some kind of compatibility.

Yes, it is text but without /meaningful/ semantics. It is nearly impossible to convert some plain text into some meaningful DocBook XML document automatically. (Ok, with some fancy regex hackery you *could* try to find URLs in your text and convert them to ulinks. But the problem still persists.)

The truth is that we badly need a wysiwyg xml editor. there are some, but none really satisfactory (neither emacs), so write one should be really a good thing, even for a single dtd

Look at [1]. There are lots of good XML editors -- either commercial or free. Tom ----- [1] http://wiki.docbook.org/topic/DocBookAuthoringTools -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Technical Editor Maxfeldstrasse 5 /\\ Documentation Team 90409 Nuernberg, Germany _\_v http://www.suse.com

On Tue, 9 May 2006, Alexey Eremenko wrote:

Anyways I have a good idea: I would like to write a guide "Introduction to Linux Command-Line" in a cross-distro manner, but with distro-specific plugins. A Slackware book might be modified. With SUSE specifics added.

But how to implement the very new concept of plug-innable documentaion is still an open question. Also how will other people value that ?

Well, maybe you should have a look at the novdoc project. We already do something like plugins in documentation, it is called profiling there. For example, we use attributes like arch="amd64" as attribute to a tag and thus select a part of the text only for this architecture. Have a look at http://forgeftp.novell.com//novdoc/susemakedoc.pdf to find out how this all works. Berthold -- ------------------------------------------------------------------ Berthold Gunreben SUSE Linux GmbH -- Dokumentation mailto:bg@suse.de Maxfeldstr. 5 http://www.suse.de/ D-90409 Nuernberg, Germany

Rajko M wrote:

Now back to square one. We have to rethink the opensuse.org structure, vote and do as agreed. Guys from documentatio team have huge experince in structuring books ie. chapters and indexes, and can give initial idea how to organize namespace tree from documetation node (page) further.

may be not. the wiki is a kind of structure by itself. We have to learn the wikiway and use it. I tryed do do so in the french wiki (see the docs layout in http://fr.opensuse.org/Utilisateur:Jdd), but I'm far from mastering it :-) jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos

Karl Eichwalder writes:

...

Here SUSE Linux lacks badly - the KDE docs indexing takes a lot of time. (minutes or hours) a possible solution is to provide preindexed database for most docs.

That's a valid concern. There should be an option to start the indexing immediately after the installation - someone to file a feature request?

According to https://bugzilla.novell.com/show_bug.cgi?id=132703, this looks done by now :-) Will Stephenson implemented system-wide indexing. -- Karl Eichwalder R&D / Documentation SUSE Linux Products GmbH Key fingerprint = B2A3 AF2F CFC8 40B1 67EA 475A 5903 A21B 06EB 882E