Re: [jazzplusplus-devel] Doccumentation -- a scratchpad of thoughts

[Pete S. <pst...@gm...>]

D.B. Moore wrote:
PS = Pete Stieber
PS>>>> I'll try to generate an example soon.
PS>>>> I'll post when I'm done.

DM = Donald B. Moore.
DM>>> Good stuff, I'll check it out as soon as it's up...

PS>> Refresh the documentation page in your web browser...
PS>>
PS>> http://jazzplusplus.sourceforge.net/documentation/
PS>>
PS>> Scroll to the very bottom and click con the link
PS>> in the line...
PS>>
PS>> Check out an ancient version of the Jazz++ online
PS>> docs by visiting the manual page.
PS>>
PS>> That's the same content as you would see using
PS>> the online help...
PS>>
PS>> Make sense?

DM> ......yes actually....it does...however, just to be
DM> sure, here's how I understand it right now...
DM>
DM> quintessentially. jazz.tex contains -all- the
DM> documentation

I'd say all of the user documentation.  Subversion instructions, how to 
build the code... that should be on the web site.  Once we have binary 
distributions, only user documentation (history of Jazz++, how to use 
Jazz++, the new MIDI how to content you are developing...) belongs in 
the tex file.

DM> users can access these docs via a>jazz builtin
DM> help context or b> anything else they wish to
DM> view the docs generated in the jazz++ build
DM> process, whatever format that might be...
DM> (and we supply the various doc formats in the
DM> binary packages) (which end up in
DM> /usr/share/doc/jazz++ or similar)

That sounds about right.

DM> folks building from release tarballs get all
DM> the various doc formats built/converted at
DM> compile time. (if they don't want, say, the
DM> pdf generation, we could have configure switches
DM> like --disable-pdf etc....but my thinking is why
DM> bother? the doc generation takes next to no build
DM> time, we're not talking about saving oodles of
DM> drivespace to justify doc generation exclusions,
DM> so it builds the lot and users should be glad
DM> and that's that ;-)

Instead of --disable-pdf, the configure file will check to make sure 
pdflatex or pdftex exists on the machine, and complains if it doesn't.

DM> the HTML docs generated from jazz.tex form the
DM> online (web) documentation as well...

Yep.  The nice feature is we can use locally installed versions of these 
same files for the help used by the running Jazz++ binary.

DM> the document currently at
DM> /web/htdocs/documentation/index.php
DM> gets revamped, and actually acts as a
DM> contents/navigation page which refers back
DM> to (link to) various sections of the HTML docs
DM> generated from jazz.tex....
DM>
DM> ..and in this way, content of website
DM> documentation is (hopefully)
DM> always in-sync with the current *release*
DM> versions of Jazz++ as they become available....
DM>
DM> Did I get it right?  (^B

I believe we are on the same page of the docs ;-)

1. You send me patches to jazz.tex and updated or new *.png files.
2. I put them in the src/HelpFiles directory.
3. I make sure everything builds properly.
4. I move the content over to the htdocs/manual directory
5. The required files are automatically provided with the distribution.
6. You review and generate new patches.
GOTO 1

Pete