[Fedora Project Wiki] Update of "MoinDocBookProject/ProgressReports" by MikkoVirkkilä

[Karsten Wade]

Just a couple of quick comments to share.

On Thu, 2006-06-15 at 09:06 +0000, fedorawiki-noreply at fedoraproject.org
wrote:

> + I've got working chapter-import, but I haven't implemented the
> Build``Docbook action/formatter. Instead I've been thinking and
> talking about how to include additional resources the docbook needs.
> The most suitable way seems to be to make a Build``Doc``Book action,
> which calls the docbook-book-formatter to fromat the page. Then to
> harvest all images filerefs, get the images from moinmoin and put it
> all in a zip, which would get served to the user.

Sounds good.  We can use this as a starting point for more automation in
the future, e.g., a user can click [Publish to CVS as XML] or something.
Not in scope here, just discussing the trend.

> + == Mass import ==
> + Mass import would work the same way: instead of uploading multiple
> files, only one would be uploaded (zipped). This would be implemented
> as an action called something like "Import Doc``Book". The action
> would present the user with a simple upload form. Then the action
> would unzip and process the contents. First it would create a mainpage
> for the docbook book, where it would attach all the image and other
> resources. Then it would extract what chapters the book contains and
> list them on the page (wrapped in the Include``Chapter-macro). For
> each chapter it would create a subpage and run the docbook through the
> xslt to get the wikisyntaxed contents for that page. It's quite clear
> that keeping the chapter->wikisyntax xslt out of the moinmoin code in
> a spearate file is the Right``Thing to do.

Can you clarify what the separate file is?  Just want to be sure I
understand this fully.
 
>  a few interesting things have popped up that I want to mention.
> +  1. Doing something automatically when a page has been changed.
> +  2. Support for task and procedure
> +  3. Doing custom postprocessing after the formatter has finished
> + 
> + Ok, so taking these in order: 
> + 
> + Item nr 1 is something that I've been requested a lot. Currently
> moinmoin makes it possible to subscribe to pages, but the people
> requesting this want to do something automatically on the serverside
> of things. I've looked in to the code, and it's quite clear where this
> hook would go. I'd like to do it by checking if a certain
> script/executalbe exist, and if it does it would get launched in to a
> separate process, and the information pagename, comment, and trivial,
> would get passed as command line parameters. Then it would be the
> responsability of who ever writes the actual script to do what they
> please with the information. Seems like a simple and useful addition
> to me.

This definitely does sound simple and useful.  I can think of several
uses for this already.

> + Nr. 2 is more difficult. A task consists of a description, and then
> some listitems with sublists. The fact that it is a procedure etc is
> not simple to embed in to the wiki syntax, as wikisyntax has no
> support for conveying semantic information. The only solution that I
> can think of is writing a special formatter and include macro. The
> task would be placed on a separate page, and when included with
> something like [[Include``Task(pagename)]] it would get formatted as a
> task, instead of a regular list. This is non-trivial, so I won't
> probably be doing this any time soon.

This is a laudable task to consider, but there is another factor you
should weigh in considering:  many DocBook/XML writers don't use
<procedure>, they use <ol>.  Now, we know this is the wrong thinking;
there is value and a good reason to use the proper XML tag v. the one
that "makes it look like N".  But considering that it doesn't matter to
the majority of our users if a numbered list is 'meant to be' a
procedure or ordered list, that lowers the priority for this.  A
complete Wiki2XML solution would have to handle this and many other
cases.  We can safely keep ourselves focused on the most common use
cases for now.

Am I thinking too provincial (just about Fedora)?

> + Nr 3 is something I will not do. There are good enough tools to do
> this (like wget->unzip->xsltproc) when it needs to be done, but I see
> little point in making moin more complex for this.

+1

- 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/20060615/cb53118f/attachment.sig>