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

[Mikko Virkkilä]

On Thu, 15 Jun 2006, Karsten Wade wrote:

> 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.
I'm going to use one or several xsl-template(s) to do the conversion from 
docbook->wikisyntax. These templates should not be stored inside python 
code, and should not have dependencies on moinmoin, but be stored in 
separate files.

This way anyone familiar with the wikisyntax, docbook and 
xslt can improve on them. The docbook project already has an extensive 
xslt toolchain, so anyone who wants to convert docbooks is probably 
already familiar with xslt. Keeping the xslt separate from python code 
would mean that for someone who wants to improve the conversion, would not 
need to know python.

Moin would load these xslt-files in to its xslt processor, and run them on 
the docbook.

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

I'll try to implement it then :)

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

Agreed :)

>
> Am I thinking too provincial (just about Fedora)?

This special case is not amongst the hardest, but would add some 
additional docbook-only macros and more complexity to the formatter. As I 
mentioned, this isn't a priority on my list, and I was just brainstorming 
on how it could be done. Hearing that the target audience for this is not 
very large, confirms my thoughts that this should not be of high 
priority.


There is however something I'd like to do, which is add support for 
admonitions and heading rows for tables.

The current wikisyntax allows for classes to be  specified for tables. 
I'd like to add handling for when the class is 
specified to be "headerrow" or "admonition". It wouldn't be completely 
straight forward, but at least it would require no special macro and no 
changes to the wikisyntax-parser. Just some more inteligence in to the 
formatter, where it would recognize  when a table want's to have one of 
those classes, and handle that special case. Elegant and somewhat simple, 
and as a result two (very?) common cases would produce semantically proper 
docbook-elements.

I'll probably look in to these two latter cases at the end of step 2 and 
see if I have time to implement them.

>
>> + 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
> ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
>

Cheers,

Mikko