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

["Rohan Drape" <rd@xxxxxxxxxxxxxxxx>]

> Why not just write the doc in SC?

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

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?

* 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.  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.  And the editor is 
WYSIWYG, 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.

* The help files are in plain ASCII text and are stable in CVS (no diff noise).

* It is a very minimal change from the current situation.  Perhaps something like the following?

---
// SinOsc - Interpolating sine wavetable oscillator

// SinOsc.ar(freq, phase, mul, add)

// This is the same as Osc except that the table is a sine table of 8192 entries.

// freq - frequency in Hertz
// phase - phase offset or modulator in radians

{SinOsc.ar(200, 0, 0.5);}.play
...
---

Regards,
Rohan

Also, if someone does put all the documentation in an XML database and writes backends for various 
display systems then the Object.help.sc output could be just another backend.  Or the XML database 
could be a backend to the 'text files with simple conventions' database...