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

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 Tue, 9 May 2006, jdd wrote:

Thomas Schraitle wrote:

...

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

:-)

hmmm, "wrapped in some XML" doesn't necessarily imply that it has the proper tagging you want it to have. You'd still need to manually apply loads of tags that the Wiki/XML stylesheets couldn't know of, because the Wiki format is more basic than XML (or SGML). -- Jana Jaeger jjaeger@suse.de SUSE LINUX Products GmbH Documentation Maxfeldstr. 5 +49 (0) 911 74053-0 D-90409 Nuernberg http://www.suse.de

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 :-) anybody can read xml (as text), but using the markup is an other thing. Wiki markup is a simplified html. html is already a very unorganised markup and is why it's nearly impossible to write doc in html (anybodu who print html knows that) In fact, the better we can is to translate wiki/html to full text and make a handmade markup. 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. anyway, all this is _text_ and scripts can be made like sgmltools and linuxdoc to have some kind of compatibility. 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 anybody must know, however than for reasonably short documents, using an old document as frame to write a new one is not that difficult with any text editor (if I did, you can :-). 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, 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

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

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

Actually what I want is difficult to achieve. I want: 1) documentation available offline corresponding to the product. (eg SUSE Linux 10.2 - and generic Linux - and Generic UNIX - all what is relevant) 2) most parts of it installed by default. 3) documentation easy to find (currently much documentation is hard to find - and often requires internet connection) 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. *Of course, the programmer's docs doesn't need to be installed by default. In addition to skill levels ducumentation should be searchable (like google) should be devided by topics - and - standards. - like ext3 specification - or POSIX specs or RPM specs - whatever. 5) I think it is a good idea to include third party docs to SUSE Linux - if they are useful for SUSE users of course. Like "Maximum RPM" open-sourced book by RedHat or TLDP docs. SUSE does this already. (few books included, but hard to find - next to impossible unless you know the RPM's name) 6) documentation must be fast. 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. 7) multilingual docs for basic topis only - as advanced users supposed to know English. ================================ I see the above as ideal that is hard to reach. But I would try.

Do you think that the differentiation of the texts is not detailed enough?

Well yes, it is achieved - the docs *are* devided by target groups. But standards lacks: For example very few standards covered in the docs. Most standards are useful mostly for programmers & advanced users and only available online. The later is bad. I think we need to provide specs for different topics inside SUSE Linux for offline users as well. I would like to include "standards" category in SUSE Help - that will specify the things out - LSB specs, RPM specs, OpenDocument specs, HTML specs, POSIX specs, PNG format specs, NFS specs... This is damn diffficult to do - because different specs are in different sites & have different licenses - but since most are OpenSource - most standards can be added. It is *not fair* that offline users get less powerful & less documented system than online users. While we might not be able to provide everything in the world, the goal is to do it for all of the SUSE components.

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 Alexey, On Tuesday 09 May 2006 19:31, 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.

I fear, if you want to be cross-distro this needs to be an XML document. As far as I know the Linux Documentation Project writes in XML. Guess why? ;)

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

Keep in mind: Documentation is not software. What you call "plug-inable" documentation is a fairy tale. ;) It's good in theory but bad in practise. At least from my experience. Tom -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Technical Editor Maxfeldstrasse 5 /\\ Documentation Team 90409 Nuernberg, Germany _\_v http://www.suse.com

"Alexey Eremenko" <al4321@gmail.com> writes:

1) documentation available offline corresponding to the product. (eg SUSE Linux 10.2 - and generic Linux - and Generic UNIX - all what is relevant)

Relevant docs come with SUSE Linux. I something essential is missing, file an enhancement request as already said. If more is needed, set up a dedicated doc product or doc project with the help of the openSUSE build service.

*Of course, the programmer's docs doesn't need to be installed by default. [...] In addition to skill levels ducumentation should be searchable (like google) should be devided by topics - and - standards. - like ext3 specification - or POSIX specs or RPM specs - whatever.

Sounds like devel docs ;)

5) I think it is a good idea to include third party docs to SUSE Linux - if they are useful for SUSE users of course. Like "Maximum RPM" open-sourced book by RedHat or TLDP docs.

Devel doc! You must set up an Add-on Product on openSUSE.

SUSE does this already. (few books included, but hard to find - next to impossible unless you know the RPM's name)

IIRC, the yast package management knows about RPM catagories (RPM Groups); just use the view suitable for such a search ;)

6) documentation must be fast.

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? -- Karl Eichwalder R&D / Documentation SUSE Linux Products GmbH Key fingerprint = B2A3 AF2F CFC8 40B1 67EA 475A 5903 A21B 06EB 882E

Karl Eichwalder <ke@suse.de> 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