sc crossplatform future (was re: sc3 with emacs on windows?)

[andrea valle-3]

Hey Andrea,

Can you expand a little on how this is a problem? Do you just mean the  

WYSIWYG editing on Mac? I agree that cross-platform Document support  

would be great, but the help system isn't so dependant on that.

S.

Scott, I'll try to re-elaborate.

One very strong point with SC2 has always been that help files were valid documents. You can open them, evaluate them, save your document as help files.

The format was rtf.

Now, in SC3 there was the problem of generalizing the help files while retaining the same (fantastic) flexibility.

So (correct me please), the idea was to switch to HTML. On  Mac this has been quite easy by NSIdontknow technology, which allows to keep rtf-like formatting while saving to html, and to open html by converting it into rtf-like format. An HTML help files is converted into a Document instance.

The fact is that  in this way  HTML is the original help file format. This is better if compared to the more problematic rtf as in SC2. Still, HTML is not a good format to ensure automatic conversion to SC document.

It's good for Mac, not for Linux (Marije has noticed many times), and in psycollider you simply strip away all the formatting by calling "html to code" command.

But the main problem is not for reading the HTML (at the end, one can always use psycollider method: strip away all), but for writing/editing a help file.

HTML could a good choice if it were clean.

But the cocoa HTML sources are awful. If you're on mac, you have not to deal with the problem. You use Document for editing, and that's all.

What about to write a help file if your on linux/win? On other platforms, it's really complicated.

Probably, the fact is that HTML as an original format is not a good choice. 

So, there are two points:

1. HTML is  not a good choice

2. cocoa HTML is dirty, as it focuses on visual instead of content structure

The classes I proposed are very tricky and try to generalize over the mac approach by assembling an autogenerated (dirty) HTML. Significantly, they have not solved Marije's problems.

Still I don't know of devs writing help files while on win, so I don't know, but I guess they have the same troubles.

Because the problem is the (cocoa) HTML.

 

Instead, one can think of a minimal XML format as the original format.

E.g. for SinOsc (just to give an idea)

<ugen>

<name>SinOsc</name>

<shortDescirption>interpolating sine wavetable oscillator</shortDescirption>

<syntax>SinOsc.ar(freq, phase, mul, add)</syntax>

<longDescription>

Sinusoidal oscillator; a sine tone.    

Note: This is the same as Osc except that the table has already been fixed as a sine table of 8192 entries.

</longDescription>

<args>

<arg1>freq - frequency in Hertz</arg1>

<arg2>

phase - phase offset or modulator in radians

</arg2>

</args>

<example>

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

// modulate freq

{ SinOsc.ar(XLine.kr(2000, 200), 0, 0.5) }.play;

// modulate freq

{ SinOsc.ar(SinOsc.ar(XLine.kr(1, 1000, 9), 0, 200, 800), 0, 0.25) }.play; 

// modulate phase

{ SinOsc.ar(800, SinOsc.ar(XLine.kr(1, 1000, 9), 0, 2pi), 0.25) }.play; 

</example>

</ugen>

This infos could be eventually but not necessarily inserted into sources (as in that first attempts I tried for autodocs).

 I'm not a fan of xml, and more I'm an ignorant onthe topic: maybe just a wiki mark up approach could be enough for us.

The main point is that the original help sources would not be in the "dirty" html.  

So, each IDE could define a strategy for reading/writing xml (or whatever) help files.

On Mac we could think of a parser creating the usual NSRTFsomething. Nothing changes for the user while reading.

Writing the help file would require to the dev a more structured approach. But that's how it goes. 

You can write by hand the xml (wiki markup), we can write a GUI providing the required fields etc.

It would be easy to autogenerate help files from sources.

It would be easy to create pdfs. I have not update the SC help book because it's a pain to deal with html parsing. 

Just 2c

Best

-a-

_______________________________________________

sc-users mailing list

sc-users@...

http://lists.create.ucsb.edu/mailman/listinfo/sc-users

--------------------------------------------------

Andrea Valle

--------------------------------------------------

CIRMA - DAMS

Università degli Studi di Torino

--> http://www.cirma.unito.it/andrea/

--> http://www.myspace.com/andreavalle

--> andrea.valle@...

--------------------------------------------------

"

Think of it as seasoning

. noise [salt] is boring

. F(blah) [food without salt] can be boring

. F(noise, blah) can be really tasty

"

(Ken Perlin on noise)

_______________________________________________
sc-users mailing list
sc-users@...
http://lists.create.ucsb.edu/mailman/listinfo/sc-users

[Jan Trutzschler-2]

On May 4, 2008, at 8:32 AM, Eric Lyon wrote:

>  The documentation for that class is not much more than a list of  
> examples. That's the kind of documentation you don't read, you  
> reverse-engineer it.

sorry, but i disagree, for me examples are the only documentation  
that really helps me & which i like to read ;-)

_______________________________________________
sc-users mailing list
sc-users@...
http://lists.create.ucsb.edu/mailman/listinfo/sc-users

[Julian Rohrhuber]

Andrea wrote:

>
>So, each IDE could define a strategy for reading/writing xml (or
>whatever) help files.
>On Mac we could think of a parser creating the usual NSRTFsomething.
>Nothing changes for the user while reading.
>Writing the help file would require to the dev a more structured
>approach. But that's how it goes.
>You can write by hand the xml (wiki markup), we can write a GUI
>providing the required fields etc.
>
>It would be easy to autogenerate help files from sources.
>It would be easy to create pdfs. I have not update the SC help book
>because it's a pain to deal with html parsing.
>

I try to compress some issues of this discussion (in the light of
numerous past discussions over the years):

(1) should there be one single format for all sc files (excluding
classes maybe) or should there be a documentation format and a
"normal" one? It would be desirable to have a single format to
maintain interoperability for all files.

(2) the rich text approach (in whatever format) can seem weird to
people who come from either more toolbench like or more terminal
oriented practices. Rich text, on the other hand is very natural for
those who come from literary and visual practices. It would be
desirable to keep this literary programming style and make it
available on all systems.

(3) It is tedious to write and maintain well structured helpfiles
without some kind of structural separation of layout and content. The
reflective character of sclang should be reflected in the helpfiles,
too.

The various suggestions concerning these issues seem to be difficult
because there are contradictions between these three needs.



In Den Haag, James McCartney suggested Markdown as an alternative
format (http://en.wikipedia.org/wiki/Markdown) This is good for
interoperability, but in itself does not really solve (2) and (3).

It would be possible to build on Lyx and use LaTeX as a format
(http://en.wikipedia.org/wiki/LyX). Interesting, but LyX is really
not very responsive. This is a great disadvantage. But of course it
would be very interesting, and fidel to the original idea of literate
programming to have mathematical (or any other kind of) formulas.

Earlier, we had hoped that the html formatting would become more
structured with leopard. I have no idea how it looks on leopard.

If we dropped (1), it would be possible to write a little editor in
SC that has forms which can be used to fill in help file content and
save it some appropriately structured format (XML, LaTeX or
whatever). But to do this for all files is a lot of work which would
have to be done by many people and not just by a few.

Still the question would be open of how to make the other files work
on all systems.

If we dropped (2), the other ones would become more easy, but I think
it is not worth it, considering the loss.


--





.
_______________________________________________
sc-users mailing list
sc-users@...
http://lists.create.ucsb.edu/mailman/listinfo/sc-users

[andrea valle-3]

Thanks for the clarification, Julian.

If we dropped (1), it would be possible to write a little editor in 

SC that has forms which can be used to fill in help file content and 

save it some appropriately structured format (XML, LaTeX or 

whatever). But to do this for all files is a lot of work which would 

have to be done by many people and not just by a few.

Haven't we already dropped it while choosing HTML?

HTML is not a SC format, it is converted, with different luck, on different platforms (badly, a part on mac).

(Of course, it's a huge work. In any case, I can volunteer.)

Still the question would be open of how to make the other files work 

on all systems.

Hmm, I don't think I'm understanding. Actually interoperability is ensured only for plain text.

RTF are not recognized nor on win by psycollider neither on linux. So the problem is already actual. 

On different platforms, you have to copy an paste.

So, now we have three formats:

- plain text (SCD and SC for classes)

- html (help files)

- rtf (mac doc and help legacy)

the conversion among the three formats is something that only Mac really allows.

Given this, it would be easy to have:

1. plain text (SCD, SC)

2. a doc format (xml, wiki)

3. a formatting-aware format. 

(4. ah, we have also quark files...)

You noted:

If we dropped (2), the other ones would become more easy, but I think 

it is not worth it, considering the loss.

I agree. Maybe this is an argument in favor of a Qt IDE development.

Or we can at least use a clean XHTML instead of cocoa generated html,  XHTML being easier to be parsed than rtf (which has never been intended to be parsed) 

The literate programmer could define his/her visual style (I love Georgia too:-)) by a css.

So, maybe by a controlled XHTML we could put together 2 and 3.

Best

-a-

PS: you all please pardon me for the huge number of typos in my posts. I can see them only later...

--------------------------------------------------

Andrea Valle

--------------------------------------------------

CIRMA - DAMS

Università degli Studi di Torino

--> http://www.cirma.unito.it/andrea/

--> http://www.myspace.com/andreavalle

--> andrea.valle@...

--------------------------------------------------

I did this interview where I just mentioned that I read Foucault. Who doesn't in university, right? I was in this strip club giving this guy a lap dance and all he wanted to do was to discuss Foucault with me. Well, I can stand naked and do my little dance, or I can discuss Foucault, but not at the same time; too much information.

(Annabel Chong)

--------------------------------------------------

Andrea Valle

--------------------------------------------------

CIRMA - DAMS

Università degli Studi di Torino

--> http://www.cirma.unito.it/andrea/

--> http://www.myspace.com/andreavalle

--> andrea.valle@...

--------------------------------------------------

"

Think of it as seasoning

. noise [salt] is boring

. F(blah) [food without salt] can be boring

. F(noise, blah) can be really tasty

"

(Ken Perlin on noise)

_______________________________________________
sc-users mailing list
sc-users@...
http://lists.create.ucsb.edu/mailman/listinfo/sc-users

[Scott Wilson-8]

A few points:

The markup produced by the Cocoa writer is messy, but it renders well in a variety of contexts.

WYSIWYG editability of help files is important from the Mac side at least.

The problem is really editing html source, not creating help files, as the Mac client will render any simple HTML fine. Although I know some people prefer it, there's little real need to hand code html for SC doc. Nvu is for instance a cross-platform OSS WYSIWYG editor, which seems in my casual tests to deal with the existing help files fine.
Structured doc and markup is proposed more or less every spring around the time the flowers come;-). It has its merits, but would not be 'easy' to implement, and converting the existing doc would be a significant task. I'm afraid that this is going to be one of those things like a new GUI system. Until somebody 'just does it' in a convincing form, preferably with all 1000 or so help files already converted, it probably won't happen.
An alternative (and cross-platform) HTML generation/conversion scheme would be fine, providing it worked as well.
S.
On 4 May 2008, at 13:41, Andrea Valle wrote:

Hey Andrea,

Can you expand a little on how this is a problem? Do you just mean the  

WYSIWYG editing on Mac? I agree that cross-platform Document support  

would be great, but the help system isn't so dependant on that.

S.

Scott, I'll try to re-elaborate.

One very strong point with SC2 has always been that help files were valid documents. You can open them, evaluate them, save your document as help files.

The format was rtf.

Now, in SC3 there was the problem of generalizing the help files while retaining the same (fantastic) flexibility.

So (correct me please), the idea was to switch to HTML. On  Mac this has been quite easy by NSIdontknow technology, which allows to keep rtf-like formatting while saving to html, and to open html by converting it into rtf-like format. An HTML help files is converted into a Document instance.

The fact is that  in this way  HTML is the original help file format. This is better if compared to the more problematic rtf as in SC2. Still, HTML is not a good format to ensure automatic conversion to SC document.

It's good for Mac, not for Linux (Marije has noticed many times), and in psycollider you simply strip away all the formatting by calling "html to code" command.

But the main problem is not for reading the HTML (at the end, one can always use psycollider method: strip away all), but for writing/editing a help file.

HTML could a good choice if it were clean.

But the cocoa HTML sources are awful. If you're on mac, you have not to deal with the problem. You use Document for editing, and that's all.

What about to write a help file if your on linux/win? On other platforms, it's really complicated.

Probably, the fact is that HTML as an original format is not a good choice. 

So, there are two points:

1. HTML is  not a good choice

2. cocoa HTML is dirty, as it focuses on visual instead of content structure

The classes I proposed are very tricky and try to generalize over the mac approach by assembling an autogenerated (dirty) HTML. Significantly, they have not solved Marije's problems.

Still I don't know of devs writing help files while on win, so I don't know, but I guess they have the same troubles.

Because the problem is the (cocoa) HTML.

 

Instead, one can think of a minimal XML format as the original format.

E.g. for SinOsc (just to give an idea)

<ugen>

<name>SinOsc</name>

<shortDescirption>interpolating sine wavetable oscillator</shortDescirption>

<syntax>SinOsc.ar(freq, phase, mul, add)</syntax>

<longDescription>

Sinusoidal oscillator; a sine tone.    

Note: This is the same as Osc except that the table has already been fixed as a sine table of 8192 entries.

</longDescription>

<args>

<arg1>freq - frequency in Hertz</arg1>

<arg2>

phase - phase offset or modulator in radians

</arg2>

</args>

<example>

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

// modulate freq

{ SinOsc.ar(XLine.kr(2000, 200), 0, 0.5) }.play;

// modulate freq

{ SinOsc.ar(SinOsc.ar(XLine.kr(1, 1000, 9), 0, 200, 800), 0, 0.25) }.play; 

// modulate phase

{ SinOsc.ar(800, SinOsc.ar(XLine.kr(1, 1000, 9), 0, 2pi), 0.25) }.play; 

</example>

</ugen>

This infos could be eventually but not necessarily inserted into sources (as in that first attempts I tried for autodocs).

 I'm not a fan of xml, and more I'm an ignorant onthe topic: maybe just a wiki mark up approach could be enough for us.

The main point is that the original help sources would not be in the "dirty" html.  

So, each IDE could define a strategy for reading/writing xml (or whatever) help files.

On Mac we could think of a parser creating the usual NSRTFsomething. Nothing changes for the user while reading.

Writing the help file would require to the dev a more structured approach. But that's how it goes. 

You can write by hand the xml (wiki markup), we can write a GUI providing the required fields etc.

It would be easy to autogenerate help files from sources.

It would be easy to create pdfs. I have not update the SC help book because it's a pain to deal with html parsing. 

Just 2c

Best

-a-

_______________________________________________

sc-users mailing list

sc-users@...

http://lists.create.ucsb.edu/mailman/listinfo/sc-users

--------------------------------------------------

Andrea Valle

--------------------------------------------------

CIRMA - DAMS

Università degli Studi di Torino

--> http://www.cirma.unito.it/andrea/

--> http://www.myspace.com/andreavalle

--> andrea.valle@...

--------------------------------------------------

"

Think of it as seasoning

. noise [salt] is boring

. F(blah) [food without salt] can be boring

. F(noise, blah) can be really tasty

"

(Ken Perlin on noise)

_______________________________________________
sc-users mailing list
sc-users@...
http://lists.create.ucsb.edu/mailman/listinfo/sc-users

_______________________________________________
sc-users mailing list
sc-users@...
http://lists.create.ucsb.edu/mailman/listinfo/sc-users

[jostM-2]

Julian Rohrhuber wrote:

>
> If we dropped (1), it would be possible to write a little editor in
> SC that has forms which can be used to fill in help file content and
> save it some appropriately structured format (XML, LaTeX or
> whatever). But to do this for all files is a lot of work which would
> have to be done by many people and not just by a few.
>

I think this is a great idea. And I think that XML is the way to go,
because it would allow for any number of possible ways to display the
content. LaTeX is not so great, btw, if   you are not writing in
English. Formulas would be nice, but are rare enough that they can be
handled with images. If you really need forumulas, then there would be
an XML way to do that also, e.g. <latex></latex>

XML would be the closest thing to having a database format (which I once
suggested years ago). This would make the help files not only
structured, but _translating_ them into other languages would also be
incredibly easy:  simply make an editing mask for the translator, and
only display content in the foreign language if it has already been
translated (Otherwise display it in English).

If someone corrects a code example in the help, then it would
automatically be updated in every language, etc.

Having a form to enter documentation would also make entering the
existing docs a breeze.

A database format would make searching and cross referencing much
easier.  So actually why not put the help stuff in a database?  really
this is the best way. That's the best way to do complex web sites also.
After that, you can display the content any way you like.

(btw, I have a little grep gui I wrote for searching SC help and code
files. Perhaps I will make it generally available, once I get a chance
to refine it a bit.)

It also would be easy to autogenerate a database form based on analyzing
SC classes.

I would be willing to do the database work if this were agreed upon, and
with a good form for entering the content, entering the existing help
content would be the kind of thing you can do while watching television ;-)

jostM


_______________________________________________
sc-users mailing list
sc-users@...
http://lists.create.ucsb.edu/mailman/listinfo/sc-users

[andrea valle-3]

Although I know some people prefer it, there's little real need to hand code html for SC doc. Nvu is for instance a cross-platform OSS WYSIWYG editor, which seems in my casual tests to deal with the existing help files fine.

Ah, so you are saying that e.g. on Linux Marije can edit html help files generated by my doc classes with Nvu?

Because, if this is a shared solution, I can re-switch to the original, mac-centric, implementation which worked much better from  the mac user perspective (as it used actively Document).

At that point the linuxers/windowers generate a file from the help classes, and then edit it in with Nvu. Solved.

Best

-a-

S.
On 4 May 2008, at 13:41, Andrea Valle wrote:

Hey Andrea,

Can you expand a little on how this is a problem? Do you just mean the  

WYSIWYG editing on Mac? I agree that cross-platform Document support  

would be great, but the help system isn't so dependant on that.

S.

Scott, I'll try to re-elaborate.

One very strong point with SC2 has always been that help files were valid documents. You can open them, evaluate them, save your document as help files.

The format was rtf.

Now, in SC3 there was the problem of generalizing the help files while retaining the same (fantastic) flexibility.

So (correct me please), the idea was to switch to HTML. On  Mac this has been quite easy by NSIdontknow technology, which allows to keep rtf-like formatting while saving to html, and to open html by converting it into rtf-like format. An HTML help files is converted into a Document instance.

The fact is that  in this way  HTML is the original help file format. This is better if compared to the more problematic rtf as in SC2. Still, HTML is not a good format to ensure automatic conversion to SC document.

It's good for Mac, not for Linux (Marije has noticed many times), and in psycollider you simply strip away all the formatting by calling "html to code" command.

But the main problem is not for reading the HTML (at the end, one can always use psycollider method: strip away all), but for writing/editing a help file.

HTML could a good choice if it were clean.

But the cocoa HTML sources are awful. If you're on mac, you have not to deal with the problem. You use Document for editing, and that's all.

What about to write a help file if your on linux/win? On other platforms, it's really complicated.

Probably, the fact is that HTML as an original format is not a good choice. 

So, there are two points:

1. HTML is  not a good choice

2. cocoa HTML is dirty, as it focuses on visual instead of content structure

The classes I proposed are very tricky and try to generalize over the mac approach by assembling an autogenerated (dirty) HTML. Significantly, they have not solved Marije's problems.

Still I don't know of devs writing help files while on win, so I don't know, but I guess they have the same troubles.

Because the problem is the (cocoa) HTML.

 

Instead, one can think of a minimal XML format as the original format.

E.g. for SinOsc (just to give an idea)

<ugen>

<name>SinOsc</name>

<shortDescirption>interpolating sine wavetable oscillator</shortDescirption>

<syntax>SinOsc.ar(freq, phase, mul, add)</syntax>

<longDescription>

Sinusoidal oscillator; a sine tone.    

Note: This is the same as Osc except that the table has already been fixed as a sine table of 8192 entries.

</longDescription>

<args>

<arg1>freq - frequency in Hertz</arg1>

<arg2>

phase - phase offset or modulator in radians

</arg2>

</args>

<example>

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

// modulate freq

{ SinOsc.ar(XLine.kr(2000, 200), 0, 0.5) }.play;

// modulate freq

{ SinOsc.ar(SinOsc.ar(XLine.kr(1, 1000, 9), 0, 200, 800), 0, 0.25) }.play; 

// modulate phase

{ SinOsc.ar(800, SinOsc.ar(XLine.kr(1, 1000, 9), 0, 2pi), 0.25) }.play; 

</example>

</ugen>

This infos could be eventually but not necessarily inserted into sources (as in that first attempts I tried for autodocs).

 I'm not a fan of xml, and more I'm an ignorant onthe topic: maybe just a wiki mark up approach could be enough for us.

The main point is that the original help sources would not be in the "dirty" html.  

So, each IDE could define a strategy for reading/writing xml (or whatever) help files.

On Mac we could think of a parser creating the usual NSRTFsomething. Nothing changes for the user while reading.

Writing the help file would require to the dev a more structured approach. But that's how it goes. 

You can write by hand the xml (wiki markup), we can write a GUI providing the required fields etc.

It would be easy to autogenerate help files from sources.

It would be easy to create pdfs. I have not update the SC help book because it's a pain to deal with html parsing. 

Just 2c

Best

-a-

_______________________________________________

sc-users mailing list

sc-users@...

http://lists.create.ucsb.edu/mailman/listinfo/sc-users

--------------------------------------------------

Andrea Valle

--------------------------------------------------

CIRMA - DAMS

Università degli Studi di Torino

--> http://www.cirma.unito.it/andrea/

--> http://www.myspace.com/andreavalle

--> andrea.valle@...

--------------------------------------------------

"

Think of it as seasoning

. noise [salt] is boring

. F(blah) [food without salt] can be boring

. F(noise, blah) can be really tasty

"

(Ken Perlin on noise)

_______________________________________________
sc-users mailing list
sc-users@...
http://lists.create.ucsb.edu/mailman/listinfo/sc-users

_______________________________________________

sc-users mailing list

sc-users@...

http://lists.create.ucsb.edu/mailman/listinfo/sc-users