jazzplusplus-devel

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

[D.B. M. <db...@ho...>]

Greetings,


As Pete said - "I was hoping this stuff would end up in jazz.tex"

On the night, I had thought "this stuff should go in jazz.tex"


I read through jazz.tex ..all of it. It's worth doing, it remarks
a far gone time...(even if that was less than 20 years ago).

Shiny pearls like this ;

For MIDI-only operation a 486 CPU (or equivalent) is sufficient in most                     
cases.  For satisfactory audio operation a Pentium CPU with 32 MBytes                       
RAM is recommended.


Call it sentimentality on my part if you like, but I figure a copy
of the original jazz.tex file should always remain, in tact, for historical
purposes...


Anyhow, reworking jazz.tex is almost tantamount to a rewrite. I've got no
problem with that, and for sure some passages of the old text
may find their way into the new draft....but....are we happy with
the formal and layout of the old jazz.tex documentation?


A lot of the htdocs are near a point where they'll be 'frozen' for
a time - they probably won't change until the code reaches a 
point closer to an  'official' release.


The reason I concluded to just continue adding to the
web/htdocs/documentation path, was to merely make these
additions 'visible', rather than obscured in jazz.tex right now,
....because we havn't discussed a plan here, or how things will be
done....etc etc etc..

What Pete said is right -- all this stuff *should* be in jazz.tex,
the htdocs should be generated from that (to ensure that
consistency between online and in-tree documentation)....


Comments please, how are we going to approach this?


Regards,

Donald B 
_________________________________________________________________
Never miss another e-mail with Hotmail on your mobile.
http://www.livelife.ninemsn.com.au/article.aspx?id=343869

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

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

DM = D.B. Moore
DM> Call it sentimentality on my part if you like, but
DM> I figure a copy of the original jazz.tex file should
DM> always remain, in tact, for historical purposes...

It will because it us under version control.  On your Linux box, try the 
following command in the jazzplusplus/trunk/jazz/src/HelpFiles directory...

$ svn log jazz.tex

This lists all of the log messages associates with jazz.tex.  Note the 
revision numbers.  Let's say you wanted to retrieve the original version 
  from Subversion.  That would be version...  56.  Just for fun, change 
directory to your home directory and retrieve that version of jazz.tex 
using...

$ cd
$ mkdir Junk
$ svn co -r 56 
https://jazzplusplus.svn.sourceforge.net/svnroot/jazzplusplus/trunk/jazz/src/HelpFiles 
Junk

That last line should all be on one line.  Know you have the original, 
486 and all, mentioned in tex2rtf.  I'm keeping a copy of the pdf 
generated by Tex2RTF around for a reference.

DM> Anyhow, reworking jazz.tex is almost tantamount
DM> to a rewrite. I've got no problem with that,
DM> and for sure some passages of the old text
DM>  may find their way into the new draft....but
DM> ....are we happy with the formal and layout of
DM> the old jazz.tex documentation?

Here's how I look at it.  You are doing a fabulous job with the docs. 
Feel free to re-write as you see fit.  When it comes to Jazz++ 
functionality, assume we are trying to recreate what the old version 
did.  I'm sure this is documented in the old version.  I have changed a 
few things (I want to use my new knob control instead of sliders... see 
the Metronome dialog), but not much.

DM> A lot of the htdocs are near a point where they'll be
DM> 'frozen' for a time - they probably won't change until
DM> the code reaches a point closer to an  'official' release.

Exactly.

DM> The reason I concluded to just continue adding to the
DM> web/htdocs/documentation path, was to merely make these
DM> additions 'visible', rather than obscured in jazz.tex
DM> right now, ....because we havn't discussed a plan here,
DM> or how things will be done....etc etc etc..

That makes sense, but here's what I was thinking...

I simply post the HTML output of the Tex2RTF build on the web site and 
you link to it.  It will definitely look different than the main web 
site, but it should.

I'll try to generate an example soon.  I'll post when I'm done.

Pete

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

[D.B. M. <db...@ho...>]

----------------------------------------
> Date: Sat, 17 May 2008 20:05:31 -0700
> Subject: Re: [jazzplusplus-devel] Doccumentation -- a scratchpad of thoughts
> 
> DM = D.B. Moore
> DM> Call it sentimentality on my part if you like, but
> DM> I figure a copy of the original jazz.tex file should
> DM> always remain, in tact, for historical purposes...
> 
> It will because it us under version control.  On your Linux box, try the 
> following command in the jazzplusplus/trunk/jazz/src/HelpFiles directory...
> 
> $ svn log jazz.tex
> 
> This lists all of the log messages associates with jazz.tex.  Note the 
> revision numbers.  Let's say you wanted to retrieve the original version 
>   from Subversion.  That would be version...  56.  Just for fun, change 
> directory to your home directory and retrieve that version of jazz.tex 
> using...
> 
> $ cd
> $ mkdir Junk
> $ svn co -r 56 
> https://jazzplusplus.svn.sourceforge.net/svnroot/jazzplusplus/trunk/jazz/src/HelpFiles 
> Junk
> 
> That last line should all be on one line.  Know you have the original, 
> 486 and all, mentioned in tex2rtf.  I'm keeping a copy of the pdf 
> generated by Tex2RTF around for a reference.
>

Great, thanks for the brief svn tute Pete...(and for remembering
I'm new to svn....;-)

 
> DM> Anyhow, reworking jazz.tex is almost tantamount
> DM> to a rewrite. I've got no problem with that,
> DM> and for sure some passages of the old text
> DM>  may find their way into the new draft....but
> DM> ....are we happy with the formal and layout of
> DM> the old jazz.tex documentation?
> 
> Here's how I look at it.  You are doing a fabulous job with the docs. 
> Feel free to re-write as you see fit.  When it comes to Jazz++ 
> functionality, assume we are trying to recreate what the old version 
> did.  I'm sure this is documented in the old version.  I have changed a 
> few things (I want to use my new knob control instead of sliders... see 
> the Metronome dialog), but not much.
> 

okay, thanks for the pointers


> DM> A lot of the htdocs are near a point where they'll be
> DM> 'frozen' for a time - they probably won't change until
> DM> the code reaches a point closer to an  'official' release.
> 
> Exactly.
> 
> DM> The reason I concluded to just continue adding to the
> DM> web/htdocs/documentation path, was to merely make these
> DM> additions 'visible', rather than obscured in jazz.tex
> DM> right now, ....because we havn't discussed a plan here,
> DM> or how things will be done....etc etc etc..
> 
> That makes sense, but here's what I was thinking...
> 
> I simply post the HTML output of the Tex2RTF build on the web site and 
> you link to it.  It will definitely look different than the main web 
> site, but it should.

I concur....

> 
> I'll try to generate an example soon.  I'll post when I'm done.
> 
> Pete
> 

Good stuff, I'll check it out as soon as it's up...


Regards,

Donald B



_________________________________________________________________
Never miss another e-mail with Hotmail on your mobile.
http://www.livelife.ninemsn.com.au/article.aspx?id=343869

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

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

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...

Refresh the documentation page in your web browser...

http://jazzplusplus.sourceforge.net/documentation/

Scroll to the very bottom and click con the link in the line...

Check out an ancient version of the Jazz++ online docs by visiting the 
manual page.

That's the same content as you would see using the online help...

Make sense?

Pete

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

[D.B. M. <db...@ho...>]

Greets,

----------------------------------------
> Date: Sat, 17 May 2008 21:59:18 -0700
> Subject: Re: [jazzplusplus-devel] Doccumentation -- a scratchpad of thoughts
> 
> 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...
> 
> Refresh the documentation page in your web browser...
> 
> http://jazzplusplus.sourceforge.net/documentation/
> 
> Scroll to the very bottom and click con the link in the line...
> 
> Check out an ancient version of the Jazz++ online docs by visiting the 
> manual page.
> 
> That's the same content as you would see using the online help...
> 
> Make sense?
> 

......yes actually....it does...however, just to be sure, here's
how I understand it right now...

quintessentially. jazz.tex contains -all- the documentation

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

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

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

the document currently at /web/htdocs/documentation/index.php
gets revamped, and actually acts as a contents/navigation page
which refers back to (link to) various sections of the HTML docs
generated from jazz.tex....

..and in this way, content of website documentation is (hopefully)
always in-sync with the current *release* versions of Jazz++ as
they become available....



Did I get it right?  (^B 



Regards,


Donald B



_________________________________________________________________
Be part of history. Take part in Australia's first e-mail archive with Email Australia.
http://emailaustralia.ninemsn.com.au

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

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

[D.B. M. <db...@ho...>]

Greets,


----------------------------------------
> Date: Sat, 17 May 2008 20:05:31 -0700
> Subject: Re: [jazzplusplus-devel] Doccumentation -- a scratchpad of thoughts
> 
> DM = D.B. Moore
> DM> Call it sentimentality on my part if you like, but
> DM> I figure a copy of the original jazz.tex file should
> DM> always remain, in tact, for historical purposes...
> 
> It will because it us under version control.  On your Linux box, try the 
> following command in the jazzplusplus/trunk/jazz/src/HelpFiles directory...
> 
> $ svn log jazz.tex
> 

...snip.....

> 
> DM> Anyhow, reworking jazz.tex is almost tantamount
> DM> to a rewrite. I've got no problem with that,
> DM> and for sure some passages of the old text
> DM>  may find their way into the new draft....but
> DM> ....are we happy with the formal and layout of
> DM> the old jazz.tex documentation?
> 
> Here's how I look at it.  You are doing a fabulous job with the docs. 
> Feel free to re-write as you see fit.  When it comes to Jazz++ 
> functionality, assume we are trying to recreate what the old version 
> did.  I'm sure this is documented in the old version.  I have changed a 
> few things (I want to use my new knob control instead of sliders... see 
> the Metronome dialog), but not much.
> 
//personal barf
One thing I really dislike, is when parts suppliers change the order
of catalog sections every year a new edition of their parts catalog 
comes out....why do they do this?...it's like going to the supermarket
where they daily change the location of things in the store
//end

....and with this in mind, the original layout of the document will
be adhered as closely as possible. Text and descriptions still valid
for jazz++ -today- will remain. New sections will be added as needed,
inside or appended to the existing document structure, images updated
and so on. I don't want folks used to the existing manual to notice
anything different in feel&use of the revised edition, lest I be subject
to my own trivial disdains...

This posting informational only, so it's known just where I'm headed.


Regards,

Donald B
 .





_________________________________________________________________
Search for local singles online @ Lavalife - Click here
http://a.ninemsn.com.au/b.aspx?URL=http%3A%2F%2Flavalife9%2Eninemsn%2Ecom%2Eau%2Fclickthru%2Fclickthru%2Eact%3Fid%3Dninemsn%26context%3Dan99%26locale%3Den%5FAU%26a%3D30290&_t=764581033&_r=email_taglines_Search_OCT07&_m=EXT