Thanks for taking this on Steven.  Some reorganization would be very
welcome.  In a couple of weeks, I should have some time to help with
correcting the manual.  Until then, here are some thoughts.

Merging Sections I and II into III (or vice versa) sounds great.  Adding the
tables to the opcode sections also sounds like a great idea.  (This is more
the way that the old Boothe manual was organized I think).

Does the Quick Reference section have to be updated by hand?

Removing the list of opcodes in the Reference section on the front page
would be good IMHO.  Just having a list of the subsection links would be
sufficient with the lists of each reference entry on the subsection pages.

Making the "empty" pages more useful would be nice.  Many of the headings in
the table of contents link to pages with just a title.  These pages would be
better if they included a list of links to subsections IMHO.

I wonder whether the following subsections of Reference really shouldn't be
somewhere else:

The Utility Programs
Cscore 
Extending Csound 

Or at least make then more noticeable somehow?

Maybe the Orchestra and Score subsections of Section III Overview should be
separated? (Or all of the subsections on groups of opcodes be made
subsections of "Syntax of the Orchestra" ?)

There used to be a list of the various score events under "Score Statements"
in the Reference Section.  Clicking on this link still gives a page with no
list of all available score statements.  The only way to get to the
individual pages now seems to be with the next and previous links.

The s score event page has not been updated to reflect the new feature of
specifying an end time.

Anyway to get rid of the repetition of the opcode name at the end of its
reference entry?  (Or are those there for a reason?)

Well, that's enough thoughts for now ;)

Thanks again.

Anthony Kozar
anthonykozar AT sbcglobal DOT net


Steven Yi wrote on 4/10/06 4:15 PM:

> After this initial organization, I think the opcode sections that
> currently only list opcodes should be updated to use the format Andres
> Cabrera introduced for the GEN routines:
> 
> http://www.csounds.com/manual/html/ScoreGenRef.html
> 
> where the relevant opcodes for a section are listed in a table with
> their short information next to it to facilitate better browsing of
> information.
> 
> Any feedback on these proposed changes would be appreciated!

Thanks for this important work, Steven.

The main reason that I ask for the opcode list to not be on the front page
is because it is SO long.  This has two consequences for me that make it
annoying to use the manual.  First, the contents page takes a long time to
render on my old machine (just counted - takes 10+ seconds with a local
copy).  I experience this "lag" every time I hit the back button.  Second, I
personally find it difficult scrolling through all of those entries to find
the topic that I want.  Especially when all I want is to locate the score
reference section or something.  But even when I want to find a specific
opcode, scrolling to the right one can be difficult.  (1)

If the opcode list was on a separate page, I could bookmark both the
contents and opcode index pages and choose which one would be faster for a
particular lookup.  I don't know how difficult this would be either, but a
line of alphabetical links "A B C D ..." on the opcode page like the Boothe
manual had would be very helpful.

Maybe the best solution would be for me to see if it is possible to create
an alternate contents page using DocBook that will do what I want but not
interfere with the current page that others seem to like.  I will attempt to
do this at some point :)

Thanks again.

Anthony

(1) Maybe I am approaching the user interface incorrectly, and using the
scrollbar is the problem.  However, my browser's search function is not as
nice as Mozilla's and when I try to search for the "max" opcode for
instance, it stops on every word with the string "max" in it first (like
"maximum").  *shrug*


Steven Yi wrote on 4/14/06 3:43 AM:

> Just a quick note, I've just started on reorganizing the manual.

> I largely agree with everything you wrote but am not sure about the
> opcode page.  It does make it easy to hit the manual home page and use
> a browser's find capability to find an opcode, but there might be ways
> to organize that too.  (I have to look into suppressing subsections on
> a case-by-case circumstance versus generally limiting number of
> sections to index).
>