Hello, on Montag, 4. Oktober 2010, Thomas Schraitle wrote:
On Monday 04 October 2010 Christian Boltz wrote:
[...]
I'm not sure about that. I don't say that it will be very easy, but it should be possible, and it won't be too hard.
You are underestimate the efforts.
We can make a shout match out of this ("No, I don't" ;-) - but I'd prefer to use the time more productive. I still think using the wiki wouldn't be too hard (with some creative template usage), but I also like your idea of using a WYSIWYG XML editor. <written after otherwise completing the mail> After googling around a bit (see linklist at the end of this mail) I still tend to using the wiki because there are some (at least at the first look) working converters available, while using bitflux would maybe cause more work - it looks like the editor is only the frontend, and the server-side handling would need to be written. Another advantage of using the wiki as base would be that we can easily create an "offline copy" of the wiki (for regions without useable internet access) or of a set of pages (for example a build service manual). </written after otherwise completing the mail>
90% of the formatting can be done with plain wikitext, and for the remaining 10% templates can be used (which can, but don't have to have a visible effect in the wiki). A "visible" template might be something like "text printed on screen", an "invisible" template might contain a keyword for the book index.
We use a feature in DocBook/Novdoc what is called "profiling". We label one paragraph for business related products and another one for openSUSE products. When we process the manual, the paragraphs are being "filtered" so only the requested product is visible in the end format. Maybe this belongs to the remaining 10%...
That could use something like {{only_openSUSE|paragraph text}} or {{only_SLES|paragraph text}} and the template would just be {{{1}}} to show the text and empty to hide it. Or, to make it a bit more flexible and to allow multiple targets without duplicating the content, something like {{onlyIn|SLES,SLED|text}} could be used in combination with ParserFunctions.
I think we could even develop a "XML skin" for mediawiki so that the wiki can generate valid docbook/novdoc XML out of wiki pages (with <para> instead of <p> etc.). The alternative solution would be to post-process the wikitext or the HTML to convert it to XML.
Depending on the HTML this sounds scaring.
The advantage of the wiki is that it is _generated_ HTML (from wikitext), so it won't be too scary ;-) ...
I'm afraid that the learning curve is too high - lessons for lizards unfortunately gave you/us that lesson...
Sorry, but I never understood the "XML is too difficult" rant. People are *not* afraid to learn LaTeX or Wiki, dig into HTML, or even migrate from Windows to Linux because of "the learning curve is too high". Why they are not afraid? Because they are _interested_ and want to _learn_ something new.
Or because they need it (for private usage or for the job) and _have to_ learn it.
Why should it be difficult to learn DocBook/Novdoc? It's just a format as HTML, WikiText, ASCIIDoc, or anything else. Maybe it's a bit more verbose, but if you can write HTML and design your webpage, you can also write documentation in DocBook or Novdoc. It's just a matter of your XML editor.
I think we should "split" the potential editors in two groups: a) people that want to do large contributions, for example a new chapter about <insert topic here> They will probably have no problem with learning the needed XML, and they'll probably also fit your "want to learn something new". Even if they initially didn't want to learn XML, the effort is small compared to writing all the text, and therefore acceptable. b) people that "just" want to fix a small error or a typo I doubt that they will happily learn XML "just" to fix a typo or mark a link as a link - the effort to result quotient is too bad in this case ;-) For those people, having an "Edit" link in the online version of the manual would be a very big advantage. ...
I don't know if the learning curve was the only problem there, but at least it's "I have to learn another thing before I can contribute".
I'm afraid, I have to disagree here. "To learn another thing before I can contribute" is the case for _every_ open source project. If you want to contribute, you usually use what's there. If you are interested enough then you are willing to take that "extra step". If not, you simply don't contribute.
Thanks for confirming my two groups from above ;-) but I'd prefer not to have that "extra step" so that everybody can contribute.
Just think of this example: People were not afraid to learn CVS. After some time, it was more or less replaced by Subversion. Although it was not that different, people were willing to learn the differences.
I think many users could just do alias cvs=svn and continue as usual ;-) because the features most people use (co, up, diff, commit) are basically the same.
Now it seems Git will be the sucessor for Subversion. And *that* is really different from CVS/Subversion! And what's the opinion? "Git is soo coool!" is what can I heare a lot. ;)
Again, this depends on your usage and needs. I know that Git has lots of features, but IMHO that makes it also complicated when compared to SVN. Personally I'd say I know SVN quite well, but don't really know Git because I didn't really need it until now. The good thing is that at least the checkout/clone is quite easy (and copy&paste-ready available on most project homepages) - without knowing all details of Git, I can still send a patch or post it in the bugtracker. Developers who use Git in their daily work will of course know it better and just ask the upstream developers to pick their changes from their private Git repo. Back to the manual: the question is if we need another tool which every contributor has to learn (XML), or if we can use an existing one (wiki).
Let me suggest another idea: In my opinion, most people have problems with XML because it's (a) too verbose, (b) it's too "complicated", and (c) you don't see the result. At least that's what I hear a lot.
Yes, that sums up the problem quite good.
As most of the functionality thesedays goes through the Web, why not have a XML editor in, let's say, Firefox?
Of course, it should offer the usual features but would hide the XML syntax and display just the rendered text. I know, this is day-dreaming and the idea is not new. However, I think, this would lower the entrance. We could use the existing XML source without converting it to Wiki while embracing Web usability. I think, this should solve the above problems.
Indeed, this sounds like a very good idea. Since we are already dreaming: the HTML version of the manual should have an "[Edit]" link attached to every section ;-) We would also need an easy way to create a new chapter, but that has lower priority because it isn't needed too often compared to fixing errors or adding some details in the existing chapters. If it works as expected, it would be a good solution that would make contribution easy (that's the main problem with the current manuals).
Maybe we could use Bitflux, see http://bitfluxeditor.org/.
The description on the homepage looks promising. Unfortunately the demo seems to be broken (lots of "not found" errors for the JS files)...
[...] I see the public SVN as a fast solution so that people have a chance to dig into the manual's source. It might even be read-only in the beginning - having to upload patches to bugzilla or send them to the -doc mailinglist is still easier than reporting "on page 123 in section 'foo', there's a typo in 'baar'".
A page number is a bad choice as it can change easily. Better use the section title or an anchor from HTML. :)
I was more thinking of PDF or printed manuals in this case ;-) BTW: I think Jana Jaeger can tell you a story about printed manuals and paperclips. hint: bug 65000 *g*
You have to "switch" from the rendered manual (HTML, PDF, ...) to the XML source, and you have to know at least some XML basics.
In Wikis you have to know some Wiki basics. What's the point here? :)
I see several points: - the wiki has a "preview" button where you can see your changes. That's not WYSIWYG, but not too far away - lots of people know wiki basics (think of all the people that write in wikipedia) - and even if you don't know wiki syntax, I'd say it is very easy to understand - for example, a paragraph is just, well, a paragraph. More important (and missed in your question) is the "switch" from the rendered manual to XML source. Finding the correct place to edit in the XML can be more difficult than doing the actual text change. That's where the wiki is really good with an "[Edit]" link at every section.
OTOH the wiki is more like a long(er)-term solution, but makes contribution much easier - just click "Edit". ... Although I'm not that much into the Wiki topic, I have the impression the Wiki syntax is not very well "established": One Wiki supports a certain syntax, another don't. If this is really the case, I wouldn't call Wikis "a long-term solution".
Yes, there is indeed some wiki software with slightly different syntax. I don't really see a problem in that because the software we use (Mediawiki) has a well-defined syntax and is broadly used (wikipedia). BTW: HTML and CSS have a similar "problem" - some browsers understand additional tags or even misinterpret some tags. Does this mean nobody uses HTML? ;-)
For easier contribution: See my idea above.
Indeed, an online editor for the manual would be a very good idea. The main reasons why I proposed using the wiki are: - the "[Edit]" link - that makes finding the correct place for an edit easy (no need for grep, searching in the file etc.) - already well-known or at least very easy to learn syntax - result visible instantly When I wrote my proposal, I wasn't aware of Bitflux, and therefore the wiki was the tool that fulfilled the above requirements best. If Bitflux can do all that and additionally keep the XML format, then it might even be better than using the wiki.
Yes, writing a good wiki-to-XML tool will need some work, but it is possible. And it is worth the effort IMHO.
Why should we write some wiki-to-XML converter when we have already everything in place, ready to be used?
To make it easier for contributors. But see above... Let me paste some links that might be useful for the discussion and/or technical implementation. Note that I just had a quick look at the following pages. https://wiki.ubuntu.com/DocBookWeb and http://fedoraproject.org/wiki/Converting_wiki_to_DocBook_XML overview on several tools for wiki -> docbook (seems openSUSE is not the only project that has a need for this) http://code.google.com/p/gwtwiki/wiki/Mediawiki2Docbook looks like working code, page mentions "partial working", so the converter might need finetuning http://www.mediawiki.org/wiki/Extension:XML_Bridge http://www.mediawiki.org/wiki/Extension:Collection Mediawiki extensions for docbook export http://toolserver.org/~magnus/wiki2xml/w2x.php online converter for wikitext -> docbook (and other formats), source available http://doc-book.sourceforge.net/homepage/ a wiki working with docbook format internally http://www.tldp.org/wt2db/ command-line wikitext -> docbook converter And now to the fun part:
You compare apples with oranges. :)
Why not? Both are round, and you can eat both of them ;-)) Regards, Christian Boltz -- Lies halt mal dclp.*, da faellt dir nix mehr ein. Wenn man ein Guerteltier ueber die Tastatur abrollt, kommt besserer PHP Code raus als da gepostet wird. [R. Huebenthal in darw] -- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org