| Regarding Csound manual formats:
I don't know what SGML is, but if it was chosen by the Linux crew,
and it can be converted into various things including HTML, then it
sounds worth looking into.
I am a stickler for typography and layout. I really like Microsoft
Word. I see the electronic form of the manual as important, but what
it looks like on paper is the most important thing for me. Of course
it should look that way on screen too.
Being able to put page breaks where you want, have headings, tabs,
fixed width fonts (though how do you do tabs properly with courier)
and various typefaces is fantastic.
Word can be converted to PDF if you buy the program, which I haven't.
Of course it can be converted to Postscript. Both conversions
make assumptions about page size for printing.
Carefully laid out Word files also make assumptions about page
size. A problem is that one or two countries are A4-challenged
and stick with smaller "Letter" size paper.
HTML has its problems, like not being able to easily do propotional
space text that looks like this:
Indented heading Text, text, text, text to a fixed margin
text, text etc etc etc etc to that margin
However, HTML has a *lot* to be said for it.
Plain ASCII is an non-starter as far as I am concerned for a serious
manual. You need diagrams, bold-face, headings, italics, different
fonts etc.
If everyone had a Word viewer, or Word could translate its output to
HTML, with all formatting intact then I would vote for that, but HTML
can't do all the formatting. I don't think you can even force
page-breaks.
Unless SGML has important advantages, and can be written by most
potential Csound authors, then I vote for people creating HTML by
whatever means they like, following a generally agreed formatting,
and submitting their file to an online manual maintainer to put it in
a particular location in a WWW site.
Ideally the manual would have just a lot of reasonable sized (2 to 50
k ?) files, all in one directory, but as the thing grows, there will
probably need to be sub-directories.
We probably need to use long file names for the HTML files, not just
MSDOS 8.3 style names.
This way there could be a single WWW site with the "Official Csound
Manual" consisting of:
HTML files (maybe produced from SGML?)
ASCII text files including example .orc, .sco and .C files.
.GIF and .JPG files for graphics.
There could even be short audio files could be there too.
Then Net connected users can read and print at will. In the long term
future most of us will be permanently net-connected.
There should also be Gzip format .zip versions of the manual
available. They can be unzipped on any platform Csound is likely to
run on (I think). This means people can download the entire manual
as a single .zip file and unzip it, sub-directories and all, on their
own machine.
If graphics, .orc, .sco and audio files become bulky, then there
could be two or more versions of the .zip files - with and without
these file types.
I understand that my ugens will be incorporated into a forthcoming
"official" Csound version from John Fitch. The documentation for
them is in various ASCII files in the .zip file at my Web site.
If there is a single, unified Csound manual approach, I would be very
happy to rewrite these to the required format (in terms of layout,
style, method of explaining the op-code etc.) in the require file
type - which I imagine will be HTML with graphics as required.
- Robin
. Robin Whittle .
. http://www.ozemail.com.au/~firstpr firstpr@ozemail.com.au .
. 11 Miller St. Heidelberg Heights 3081 Melbourne Australia .
. Ph +61-3-9459-2889 Fax +61-3-9458-1736 .
. Consumer advocacy in telecommunications, especially privacy .
. .
. First Principles - Research and expression - music, .
. music industry, telecommunications .
. human factors in technology adoption.
. .
. Real World Interfaces - Hardware and software, especially .
. for music . |