audacity-devel

Re: [Audacity-devel] Manual download and installation

[Richard A. <ri...@au...>]

On Fri, 2011-09-23 at 00:49 +0200, Benjamin Drung wrote:
> > > I checked the help.zip file and ask myself why we don't have that
> > > packaged as audacity-doc.
> > > 
> > > The zip file should be versioned. So that it is easy to see to which
> > > version of audacity the help belong. Maybe you could put the help zip
> > > file on http://code.google.com/p/audacity/downloads/list too. The help
> > > zip does not contain any copyright and license information. Without that
> > > it is impossible to get it into the Debian archive.
It would make a lot of sense to have a version zip file of the help for
each source tarball in the Google code downloads. This would also make
it easy to add a documentation use-flag to the Gentoo ebuild which would
install the manual when the package is installed if the user wants it.

With this in mind, should we alter the release process so that the
manual is zipped once and then that content put into each installer,
rather than each installer build process getting their own download of
the manual as at present?

What it would be worth doing I think is adding two new makefile targets
- "make help" to generate the file tree of help files as per the
existing batch file and "make helpzip" to make the zipped file based on
the file tree. This would allow for making zip files easily on Linux /
Mac as is done on Windows.

> > The docs are copyright and licensing is CC by 3.0:
> > http://creativecommons.org/licenses/by/3.0/
> > 
> > both of which are stated at the bottom of the Manual front page. 
> > 
> > Do you need more to package the help.zip file, if so what - a 
> > License.txt file? 
> 
> It would be better to have a License.txt file in the help.zip file. Who
> owns the copyright for the files?
Audacity has never done copyright assignment, so I assume (as with the
source code) that anything contributed has the copyright remaining with
the author, but is licensed under the relevant license, in this case the
Creative Commons Attribution 3.0 license.

We can include the standard Audacity Licence.txt file in the zip file
easily enough by altering the build script.
 
> > One issue that occurs to me is that Ubuntu/Debian and Audacity 
> > releases rarely coincide. When you package Audacity for a distro 
> > release do you pull HEAD, or just use the latest Beta tarball (then of
> > course add any of your own patches)? If you pull HEAD, then the 
> > better approach (given we now aim to keep the online Manual 
> > up-to-date with HEAD) might be to pull and version the Manual 
> > yourselves using /scripts/mw2html_audacity/wiki2htm.bat in 
> > the source tree.
> 
> We use the (latest) Beta tarball in the official Ubuntu/Debian archive.
> 
> We like to have the sources in the form in which they are modified. For
> binaries it is the source code. For documentation it is the format it
> was written in. Would it make sense to have a 'source documentation
> tarball' containing a 1:1 copy from the wiki and the mw2html script? Or
> is the 1:1 copy from the wiki as useless form modification than the
> static html pages?

There isn't really a 1:1 copy form for a mediawiki instance, short of a
full server backup. The mediawiki export function requires a page list
in order to work, which doesn't currently exist (our scripted export
works on a spider-like basis. More importantly, the mediawiki export
doesn't contain any images, so they would have to be retrieved
separately.

The basis for moving a wiki is usually a mysql dump and a tarball of the
images directory, but they are of limited practical use if you want to
modify the manual, because you would have to create your own mediawiki
server to load them into, with no way of passing changes back to us.

What you actually edit is wikitext, which is not HTML but a simpler text
mark-up, which lives in the back-end database and is passed out to the
web page edit dialogue (or another off-line editor) on demand. So unlike
Docbook or Latex, there aren't a set of "source" files anywhere other
than in the database.

The bottom line is that the preferred form for changes is strongly to
make them to the on-line wiki, and the off-line files are predominantly
a snapshot for archival purposes, and those who aren't online when they
use audacity.

Richard

Re: [Audacity-devel] Manual download and installation

[Gale A. <ga...@au...>]

| From Richard Ash <ri...@au...> 
| Fri, 23 Sep 2011 15:47:20 +0100
| Subject: Manual download and installation
> On Fri, 2011-09-23 at 00:49 +0200, Benjamin Drung wrote:
> > > > I checked the help.zip file and ask myself why we don't have that
> > > > packaged as audacity-doc.
> > > > 
> > > > The zip file should be versioned. So that it is easy to see to which
> > > > version of audacity the help belong. Maybe you could put the help zip
> > > > file on http://code.google.com/p/audacity/downloads/list too. The help
> > > > zip does not contain any copyright and license information. Without that
> > > > it is impossible to get it into the Debian archive.
> It would make a lot of sense to have a version zip file of the help for
> each source tarball in the Google code downloads. This would also make
> it easy to add a documentation use-flag to the Gentoo ebuild which would
> install the manual when the package is installed if the user wants it.
> 
> With this in mind, should we alter the release process so that the
> manual is zipped once and then that content put into each installer,
> rather than each installer build process getting their own download of
> the manual as at present?

That makes sense to me, not least that it guarantees each platform  
has the same "copy" of the Manual. But it's important in my view the 
zipping is done on Windows so that there is no "help" folder inside
the zip (otherwise two "help" folders will be produced in most 
Windows unzip tools and the Manual won't be found). 

 
> > > The docs are copyright and licensing is CC by 3.0:
> > > http://creativecommons.org/licenses/by/3.0/
> > > 
> > > both of which are stated at the bottom of the Manual front page. 
> > > 
> > > Do you need more to package the help.zip file, if so what - a 
> > > License.txt file? 
> > 
> > It would be better to have a License.txt file in the help.zip file. Who
> > owns the copyright for the files?
> Audacity has never done copyright assignment, so I assume (as with the
> source code) that anything contributed has the copyright remaining with
> the author, but is licensed under the relevant license, in this case the
> Creative Commons Attribution 3.0 license. 

Unlike source code or web site files there are no authors stated in the 
Manual files, though. If that was important we could I suppose link to
http://manual.audacityteam.org/man/Credits ? 

"About Audacity" in the app has a generic "Audacity® software is 
copyright© 1999-2011 Audacity Team." 
 

> We can include the standard Audacity Licence.txt file in the zip file
> easily enough by altering the build script.

If we do that should we retire the outdated: 
http://manual.audacityteam.org/man/License ? 



Thanks, 



Gale

Re: [Audacity-devel] Manual download and installation

[Richard A. <ri...@au...>]

On Fri, 2011-09-23 at 17:03 +0100, Gale Andrews wrote:
> | From Richard Ash <ri...@au...> 
> > With this in mind, should we alter the release process so that the
> > manual is zipped once and then that content put into each installer,
> > rather than each installer build process getting their own download of
> > the manual as at present?
> 
> That makes sense to me, not least that it guarantees each platform  
> has the same "copy" of the Manual. But it's important in my view the 
> zipping is done on Windows so that there is no "help" folder inside
> the zip (otherwise two "help" folders will be produced in most 
> Windows unzip tools and the Manual won't be found). 

What folders are in the zip archive has nothing to do with the operating
system the script is executed on, only with the correct arguments to the
archiving program.

Thank you for pointing out that the structure of the zip archive
matters, as per process point 9 of
 http://wiki.audacityteam.org/wiki/Release_Process
however it is misleading to suggest that the operating system used will
control what structure is created, which depends purely on the tools
used to create the zip file.

I believe (although I have not yet tested) that the command required is
 zip -rv manual.zip help/
from the top of the build tree.

Richard

Re: [Audacity-devel] Manual download and installation

[Gale A. <ga...@au...>]

| From Richard Ash <ri...@au...> 
| Fri, 23 Sep 2011 17:58:53 +0100
| Subject: [Audacity-devel] Manual download and installation
> On Fri, 2011-09-23 at 17:03 +0100, Gale Andrews wrote:
> > | From Richard Ash <ri...@au...> 
> > > With this in mind, should we alter the release process so that the
> > > manual is zipped once and then that content put into each installer,
> > > rather than each installer build process getting their own download of
> > > the manual as at present?
> > 
> > That makes sense to me, not least that it guarantees each platform  
> > has the same "copy" of the Manual. But it's important in my view the 
> > zipping is done on Windows so that there is no "help" folder inside
> > the zip (otherwise two "help" folders will be produced in most 
> > Windows unzip tools and the Manual won't be found). 
> 
> What folders are in the zip archive has nothing to do with the operating
> system the script is executed on, only with the correct arguments to the
> archiving program.
> 
> Thank you for pointing out that the structure of the zip archive
> matters, as per process point 9 of
>  http://wiki.audacityteam.org/wiki/Release_Process
> however it is misleading to suggest that the operating system used will
> control what structure is created, which depends purely on the tools
> used to create the zip file.
> 
> I believe (although I have not yet tested) that the command required is
>  zip -rv manual.zip help/
> from the top of the build tree.

Thanks, OK I gave it a go on Ubuntu 10.10 with the manual at 
~/audacity/help/manual/  ("audacity" being root of my tree) and 
running that command from from ~/audacity$. 

That produced "manual.zip" in the "audacity" folder 
(~/audacity/manual.zip) and it seems structured fine. The only 
issue is the one I was driving at which is that there is a "help" 
folder in the zip with ("manual" inside that), as opposed to 
http://manual.audacityteam.org/help.zip which has no "help" 
folder. 

I was only really thinking of typical GUI tools found on the
particular platform so you're right, with the proviso that I think 
we need to provide "help.zip" not "manual.zip" to accommodate 
what most Windows GUI unzip tools will do. 





Gale 

Re: [Audacity-devel] Manual download and installation

[Alberto Z. <a.z...@gm...>]

Hello World
I just signed up this project...I would want to contribute. I have to fix
just some thing with C++ language and I will ready.
I would envelope the MIDI section of this project

Alberto Zichitella