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

[Scott Wilson <sdwilson@xxxxxxxxxxxx>]

I received this proposal from someone not on the list. Comments anyone?

Just for reference, the current strategy I'd been exploring was an HTML based doc. This is rendered by NSTextView in SC, and converted back to HTML when saved. 

Pros: The online/swiki hosting of the doc idea is easily implementable. The doc remains transparently editable and executable in SC on OSX. (Basically the same as any other Document) Clickable links to other files.

Cons: Not transparently editable on Linux, at least not without something similar in place to convert the doc from html to ? and back. Some more complicated HTML features (eg tables) could get lost when written back to HTML by SC. (There may be ways to fix this if needed, and it does not prevent doc from containing such elements, only from editing them in SC.) Probable need to conform to a few conventions (maybe not a bad thing), for instance writing all code in a particular font to maintain tab stops.

I think the proposal below is interesting, but I'd appreciate thoughts from others possibly more knowledgeable about XML.

S.

Begin forwarded message:

> From: Orm Finnendahl <finnendahl@xxxxxxxxxxxxxxxxxxxxxx>
> Date: February 6, 2004 4:41:43 AM EST
> To: Scott Wilson <sdwilson@xxxxxxxxxxxx>
> Subject: html doc
>
> Hi Scott,
>
> I'm not member of sc-users so this mail got forwarded to me by Stefan
> Kersten and I reply somewhat late.
>
> I'm planning for some time now to get a supercollider documentation
> project going. I didn't really announce it yet as I'm very busy at the
> moment and I have found this is going to be involve major work,
> considering the state of the documentation at this point. In addition
> it only makes sense to announce once it is more or less clear that it
> will get finished. I'm quite dedicated to get it going, though, as my
> teaching probably will concentrate around sc in the near future. Maybe
> we can join our efforts?
>
> I'm using linux and am interested in some platform-independent easy
> maintainable design. Therefore I would strongly vote for structural
> markup (I'd go for xml-docbook). Adding the markup isn't all too much
> work for someone wanting to write and add a quick help file in the
> future and there are validating parsers which could get used to do
> some syntax checking before new files get commited to the main tree.
>
> The idea is to maintain a source tree of xml documents which then get
> translated into pdf and html by scripts.
>
> I already made some tests and it seems quite feasible to translate the
> existent sc documentation to xml automatically (I programmed some
> converters of the original rtf into scheme, which makes it fairly easy
> to generate xml documents from these sources). In addition the format
> of xml is pretty straightforward even for non-experts as headers and
> footers aren't needed in the design I imagine. Only the different
> elements have to get tagged and I could provide a quick reader and
> tutorial about the different elements available and how to do it.
>
> Let me know what you think. It will still be quite some effort
> necessary in specifying the format types needed and managing the
> overall structure, but I think it is well worth the effort as
> maintenance will be much less pain. In working together we might be
> able to save ourselves a lot of time and still get an optimum result.
>
> Please feel free to forward it to the list.
>
> --
> Orm Finnendahl