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

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

On Feb 8, 2004, at 7:20 PM, Rohan Drape wrote:

Why not just write the doc in SC?

Or why not even just as plain text .sc files, ie SinOsc.help.sc?

because it looks like crap.

I want something that is not worse than what we have now on OSX but that the linux people can use.
Plain text is worse.
A bad thing about HTML is that you cannot edit it directly.
You can WYSIWYG edit rtf.

You mean on Linux you have no WYSIWYG directly manipulable text edit format other than plain text???
What about these?

The only thing I don't like about rtf is that it is not diff-able. small changes can have global effect on the style tags.

Some nice aspects:

* Staying in the same editor and using the same keystrokes/mouse-gestures to run examples and follow references in the help files as in one's working files is very clean and intuitive. And it is what happens now?

can do that now on OSX with .rtf.

* There is no need to mark up anything. Comments are written as comments. It is easy and efficient to do syntax highlighting for SC3 code dynamically. Pointing at the text 'SinOsc.ar' or 'SinOsc.kr' or 'SinOsc' and requesting 'find help file' opens the help file, requesting 'find implementation' finds the definition and opens
the appropriate file at the appropriate place.

This all works now on OSX.

Emacs has all the infrastructure, and Vim also for people who
don't like Emacs, the problem is that they do not understand RTF. Since the RTF basically just statically defines the syntax highlighting and some font sizes it is no big loss. I am not up to speed with the OSX editor, I assume it does all this also, and if it does not then improving it wins everywhere, most importantly
in working files, not just in help files.

* If some very simple conventions are followed then help file specific font locking (ie. getting argument names in the description in bold face, getting the class name on the first line in a larger font, hiding comment open characters, etc.) and writing a script to generate HTML/LaTeX/WhatEver output is straightforward.

* Makes life very simple for maintainers/developers. If someone notices an error when reading a help file they fix the file they are reading using the editor they are reading the file with already.

Can do that now with RTF on OSX.

And the editor is

A plain text editor is WYSIWYG all right. Unfortunately WYG is not so great.

if you make a mistake with the conventions or the syntax for examples the file will look wrong
immediately, and the examples can be auditioned from the source file...

* All of the existing files can be converted automatically in one simple operation, ie just remove the RTF from SinOsc.help.rtf and write SinOsc.help.sc. The files can then be fixed gradually and with little work.

no go on that idea. sorry.