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

[James McCartney <asynth@xxxxxx>]

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?
http://www.nllgg.nl/Ted/
http://www.abisource.com

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
> WYSIWYG,

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.