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@xxxxxxxxxxxxxxxxx
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
--
fedora-docs-list@xxxxxxxxxx
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
