Post Hoary

[Sean Wheller]

On Saturday 05 March 2005 01:13, Simon Michael wrote:
> I'm not advocating any particular change here, because I think you guys
> are kicking ass and probably don't want to be guinea pigs for crazy
> next-generation wiki/doc tools. So feel free to ignore this. But let's
> not forget to think outside the box too.

Yep, outa da box is good. Thanks for your great response.

>
> Re wiki markup not being presentation neutral - first, at least some
> wiki markups, of which I know and like Structured Text best, were
> intended to be presentation neutral. STX is, assuming you don't indulge
> in html tags. It's simply a less verbose, more intuitive form of
> structured markup. Granted no-one has yet written a PDF renderer for it.
> (RST is similar and does render to PDF and everything else as far as I
> know.)

This is correct, the concept of structured text was supposed to be 
presentation neutral. Structured text and html are very forgiving languages 
and therein is the Achilles heal. In particular with structured text, is that 
it is so flexible that it is almost impossible to ensure consistant use by 
users. It is therefore difficult to predict with great accuracy that derived 
presentation formats will be rendered consistently. 

>
> Second, what if you had wiki pages whose markup was docbook ? All it
> needs is a plugin to do whatever rendering process you currently do
> offline. You could point your docbook editor of choice at it.

+1 if we can get it to round trip. That is to say:
wiki-docbookxml-editor-plugin would be good. However, be warned, this is no 
easy thing to do. As you mention there are some things wiki does and some it 
does not. This is one of those things that it does not because docbook 
editors are not easy to build. Many in the docbook community have tried 
working on this and never do they get a good solution.

There are some options though. They don't involve an editor. It involves 
programs that will convert structured text to docbook. The problem is that 
the structured text must be consistant and even then the coversion is not 
100% valid. So you need a pipe of tools and at the end you still have to 
manually fix them in order that the xml instances will be valid.

>
> Re revision control: what if the ubuntu zope site, or just the wiki
> pages, was stored as plain files on the filesystem (via
> DirectoryStorage, APE, or some other tool) ? What if those files were
> revision-controlled ? What if a svn commit was instantly reflected on
> the website, and pages could be edited using either method ? I think
> people in the zope world are successfully doing things close to this
> right now.

Yes but there problem above is still there. Also the question is if a person 
makes a small change will the whole text file be committed to svn or only the 
changes? Then how does one get those changes into an already existing, 
corresponding xml instance. The only way I can see this is if everything is a 
single object. This would result in having to many objects and slow the doc 
development time.

>
> Jeff Schering wrote:
>  > Posting to the
>  > list is much easier than tracking down the right wiki page, learning
>  > wiki markup, getting a wiki password, and then making the change.
>
> Not always. Switching gears away from reading docs, finding the right
> list address, the right person to send to, the right format to send, the
> right subject, firing up your slow mail client - these can often be more
> burdensome than making a fix to the page that's *right there*.
>
> I agree that text formatting should be obvious and documented right
> there in the form. Also I agree that the need for registration and daily
> login sucks; personally I'd drop it and try hard to deal with spam
> another way. At the least, login should be be much easier and more
> robust and something you rarely have to do again.

I think this is a non-issue. From my perspective the problem core is how to be 
able to reuse content from wiki without having to make great effort to port 
it to docbook. Under this there are various needs for publishing of 
ubuntu-docs that need consideration. Like we need a consistant location from 
which to include data into the documents. Wiki locations can change and I 
guess so to would any pointer to the file. The number of problems and 
permutations to take into consideration can be endless here. I am not sure we 
want to embark on such an expedition without a large and dedicated developer 
team.

-- 
Sean Wheller
Technical Author
sean at inwords.co.za
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050305/20afa04b/attachment.pgp>