[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[sc-dev] [Comments?]XML doc? Fwd: html doc
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.
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
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.