There is a certain amount of fixing in 4.23 that gets carried into 5, and
backporting from 5 to 4, so I think it is better if the opcode sources are
the same wherever possible to prevent inconsistencies. This would be
easiest if both manuals were in one directory, with most of the opcode
manual files being the same for both manuals.

Either two makefiles can be used, or two targets in one makefile. The
manual directory already is separate from 4.23 and 5, so that should be
easy.

Original Message:
-----------------
From: steven yi stevenyi@csounds.com
Date: Mon, 10 Jan 2005 21:37:56 -0800
To: csound-dev@eartha.mills.edu
Subject: [CSOUND-DEV:5669] RE: Docbook-XML Csound Manual


Hi Michael,

I'm glad you were able to get these working!  As for the need for a 
csound5 and csound4.23 manual, I've thought about this and haven't been 
sure what is the best way.  I'd prefer to freeze the manual module in 
cvs and keep that for csound 4.23 and either create a manual5 module or 
include the docbook-xml within the csound5 cvs, which would make it 
easier to integrate with build process and also Doxygen (similarly to 
how you have the latex documents integrated in the cvs and build file).  
So, my current preference is to replace the latex with the docbook-xml 
in the csound5 module.  After that, it shouldn't take too long to 
convert the csound5 specific manual entries you've written to docbook, 
and then finally addressing the Doxygen docs. 

I'll also then write a readme for what's required for generating the 
docbook-xml manual and where to get those.

I started to look at generating WinHelp (actually, I realized it's 
HTMLHelp, or .chm files) files today and it seems like an easy task (was 
just about to try it out but ran out of time; will test first thing 
tomorrow).  Also, generating single-page html as well as text file 
versions shouldn't be a problem.

If it seems okay with everyone else, I can go ahead and replace the 
csound5/doc directory myself tomorrow with the docbook-xml.

steven


Michael Gogins wrote:

> I did try it. I don't have fop installed properly yet so I didn't get 
> images or PDF, but it did build your whole 4.23 HTML manual after I 
> installed xslt and xml2 in MSys/local
>
> Thanks again for your work, you've done Csound (and myself) a major 
> service.
>
> I'm quite willing to go with this, but there are issues that must be 
> resolved:
>
> 1. We need a csound 5 manual as well as a csound 4.23 manual, so I 
> need to create two targets in the Makefile and to move my Csound 5 
> specific stuff into the manual in CVS. Then I can move csound5/doc 
> into the Attic.
>
> 2. We also need to integrate the API doxygen documents into the Makefile.
>
> 3. But first, we need to replace the SGML manual with your XSLT stuff! 
> As far as I'm concerned, you can do that now.
>
> ----- Original Message ----- From: 
> To: "Csound Developers Discussion List" 
> Sent: Monday, January 10, 2005 9:37 AM
> Subject: [CSOUND-DEV:5661] RE: Docbook-XML Csound Manual
>
>
> Thanks for your work, I'll try this ASAP.
>
> Original Message:
> -----------------
> From: steven yi stevenyi@csounds.com
> Date: Sun, 09 Jan 2005 22:24:55 -0800
> To: csound-dev@eartha.mills.edu
> Subject: [CSOUND-DEV:5657] Docbook-XML Csound Manual
>
>
> Hi All,
>
> I've converted the Docbook Manual from SGML to XML and modified the
> Makefile.  As it's a bit of a change, I thought I'd see if others can
> compile it first as well as get some feedback on it before replacing the
> SGML manual. I've put up a zip at:
>
> http://www.kunstmusik.com/csoundManual.zip
>
> With this zip, you'll need xsltproc installed compile to HTML and FOP
> installed to produce a PDF.
>
> For Windows, xsltproc can be found in Cygwin, or standalone Windows
> binaries at http://www.zlatkovic.com/libxml.en.html (I believe you'll
> need the libxslt and libxml zip's from there).  For Linux, most distro's
> have xsltproc installed.
>
> For FOP, it is available at: http://xml.apache.org/fop .  To get the
> graphics to work, you'll need to also install the Java Advanced Imaging
> API. Information about JAI is available at
> http://xml.apache.org/fop/graphics.html#jai .  (BTW: FOP is written in
> Java so requires a Java Virtual Machine installed; also, if you run FOP,
> I recommend editing the fop.sh file and add "-Xmx384m" to the last line,
> so it reads as such:
>
> $JAVACMD -Xmx384m -classpath "$LOCALCLASSPATH" $FOP_OPTS
> org.apache.fop.apps.Fop "$@"
>
> This increases the max ram the VM can use to 384megs, which you'll need
> for FOP to run as the manual is fairly large)
>
> I've tested this on Cygwin using Cygwin's xsltproc, MinGW using the
> natively compiled xsltrpoc, as well as Linux.  The makefile in the zip
> is set to compile with "make html" and  "make pdf", with the default set
> to just HTML.
>
> Currently, the version in CVS still uses SGML but should be encapsulated
> with respects to the stylesheets; this runs on Linux fine for me and
> produces output identical to the ACRM.  On the other hand, I've gotten
> the XML versions to run on multiple platforms, but the stylesheets are
> not tweaked to be like the ACRM.
>
> If anyone could give this a try and let me know any feedback on how it
> works for you (or doesn't), I'd appreciate it.
>
> Thanks,
> steven
>
>
> --------------------------------------------------------------------
> mail2web - Check your email from the web at
> http://mail2web.com/ .
>
>
>
>


--------------------------------------------------------------------
mail2web - Check your email from the web at
http://mail2web.com/ .

Well, how we'll be able to manage the two in one directory--at least, 
mentally keeping the two separated in our minds--seems beyond me right 
now, but then again, I've been a bit distracted with work and blue dev 
this past week.  I'll assume it will make itself apparent to me once I 
get some rest. =)

I'll go ahead and tomorrow will tag the manual repository in its current 
state as "SGML_FINAL" or something along those lines, will then delete 
everything in the repository and then move the XML version in.  After 
that, there are still some issues to resolve, but at least we'll all 
have something we can all use for generating documentation.  The issues 
I have listed are:

1)Examples from external files are currently not being brought into the 
documentation (figuring out how to do it once will be the hard part, 
after that a regular expression should make quick work)

2)Styling the documentation output

3)Integrating Csound5 documentation from latex docs

By the way, my current Makefile now has a htmlhelp target produces a 
.chm file(winhelp).  It requires Microsoft's Html Help Compiler (hhc), 
which is a free download. 

steven

gogins@pipeline.com wrote:

>There is a certain amount of fixing in 4.23 that gets carried into 5, and
>backporting from 5 to 4, so I think it is better if the opcode sources are
>the same wherever possible to prevent inconsistencies. This would be
>easiest if both manuals were in one directory, with most of the opcode
>manual files being the same for both manuals.
>
>Either two makefiles can be used, or two targets in one makefile. The
>manual directory already is separate from 4.23 and 5, so that should be
>easy.
>  
>