[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [sc-dev] [Comments?]XML doc? Fwd: html doc

On Feb 13, 2004, at 1:27 AM, stefan kersten wrote:

On Thu, Feb 12, 2004 at 12:45:59AM -0800, James McCartney wrote:
That would only handle the UGen classes. It is not very general to
handle other parts of the docs.

the problem is that implementing wysiwyg markup editing is
hard if there is no os/library support. the problem with rtf
markup in particular is that it's not easily parsable,
doesn't contain/preserve structural information, is layout
centric and in some cases the output depends on the font
used etc. -- i've yet to find an rtf editor on linux that
renders Help.help.rtf correctly.

The worst thing for me about rtf is that you can't diff it reliably. If you make a small style change it can cause the style tags in the whole document to get renumbered. Makes checking what changed in cvs a pain. One day I will finally the script that does this: get two revisions, convert to text, and diff. Then it will not be an issue.

is wysiwyg really a requirement?

Well currently if you have a help file open you can not only select and execute the examples directly, but you can also edit the values or change a WhiteNoise to a PinkNoise, etc, and see what happens. If the docs were in HTML you couldn't do that. You'd have to copy them somewhere else to edit them. Or switch to the HTML source and edit that - not very interactive - and if the text is syntax colored there will be so many tags embedded in it that it will be nearly impossible to edit. You'd need a tool to generate the html from a third representation.

 imho an html/xhtml
representation would be a viable alternative, if you can
switch between edit and view mode within the same document
interface or have proper tool support to convert to any
representation desired.