what next?

Karsten Wade kwade at redhat.com
Thu Nov 9 16:38:47 UTC 2006


I'll try to reply here with all my thoughts to this part of the thread,
rather than repeating myself into this thread-branch.  HTH.

On Tue, 2006-11-07 at 18:46 +0000, Dimitris Glezos wrote:
> So, as I see it we need a balance between a solid solution like 
> "everything in Docbook" or a usable solution like "everything in the 
> wiki or in a kbase". With the first approach 
> *publication/maintainability* is easier and more simple but with the 
> second the actual *writing* is. Second has advantages like better 
> monitoring/live results, but with the cost of less functionality and a 
> cost overhead for producing the final form.
> 
> With the MoinDocbook we try to do a little of both but it seems that the 
> transition from wiki to Docbook is not as easy nor as solid as it sounds 
> (correct me if I'm wrong here). The problem could be that we are trying 
> to maintain the content in two forms instead of one with just two 
> front-ends (the web one and the cvs-checkout/emacs one).

It's a combination of technical and procedural.  For something like the
release notes, I think the Wiki -> DB works great, ideally.  We still
have some bugs to work out, but they are minor in comparison.

> I'll throw another idea on the table (probably a bit bold too), since 
> now it's the best time to do it.
> 
> Maybe a live web front-end to the actual Docbook code in CVS/SVN would 
> be a better solution? Let's say, we can see live the Docbook results and 
> edit individual paragraphs, with each edit resulting in CVS commits? If 
> we hook this up with the accounts system, everybody will be able to chip 
> in like with the Beats system, and the result would be maintainable with 
> the power of Docobok/CVS (no need to convert). 

Not too bold at all, and has been discussed on this list before you came
around.  The idea is solid and we defined some ideas of how to do this
with the upcoming code in Moin Moin.  The basic idea is to have Wiki
constructs for easy block code (<para>, <itemizedlist>, etc.) and then
find some way to expose actual XML within the Wiki itself.  (This is
what 'DocBook Wiki' does that you reference below.)

Personally, I think we need to pursue this with Moin and the plans Mikko
and I made over the summer:

http://fedoraproject.org/wiki/MoinDocBookProject/PassThroughBlocks

Read through this entire road map to understand a little more:

http://fedoraproject.org/wiki/MoinDocBookProject/RoadMap

> I searched a bit and 
> found a project that does exactly that:
> 
>   http://doc-book.sourceforge.net
> 
> I don't know if it's worth it (the customizing etc.), but it could be a 
> candidate to substitute the wiki <-> docbook conversion. It is written 
> in PHP, it uses xmltproc and friends, it seems to support multiple 
> languages, content approving, intermediate docbook-focused syntax (or 
> docbook). Last update was 1.5 year ago.

We took a serious look at this internally at Red Hat and ran into
several show-stoppers.  The content is stored in the SCM (CVS or SVN) in
a very unique way that is hard to map to DocBook needs.  In fact, iirc,
we could not use XIncludes properly because of the directory structure.
There were other technical limitations that don't come to mind; Jeff
Fearn might be able to enlighten us further here, if he wants to
decloak.

There are also concerns about maintainability.  This DocBook Wiki would
setup an entirely new piece of infrastructure that no one is familiar
with, and FI is not interested in supporting.  It is also a bit out of
date, and while I don't think Dashamir has abandoned the project, it
does not seem to be his main focus.  So, we would likely need to have
someone become an active upstream supported to have success.

With Moin, we have all that already -- it is understood, supported, and
we are working with the very active upstream to get our changes in and
supported, probably maintained by someone from Fedora.

I will balance this with saying that actually looking at the UI for
DocBook Wiki makes it look like a great idea; it is rather elegant the
way he made it work, which is where I got the idea to embed XML within
the Wiki markup.

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061109/de58dd36/attachment.sig>


More information about the fedora-docs-list mailing list