Re: [Audacity-devel] HTML Manual distribution

[Martyn S. <mar...@gm...>]

Hi Richard!

Very well thought through arguments, thank you.  I agree entirely (and 
nobody has disagreed, so far).

To do this we need:

1 That cross-platform script to get the manual (I think we have that, 
mw2html.py) and to zip it consistently (we don't have that).  Maybe 
just agreement on zipping it consistently would do, put the 
instructions on http://wiki.audacityteam.org/wiki/Release_Process 
somewhere.

2 Changes to http://wiki.audacityteam.org/wiki/Release_Process#Process 
on step 5: add the bit about running the new script and making the zip 
available on http://code.google.com/p/audacity

3 Changes to audacity.sln to stop it building the manual (deletion of 
the 'help' project).

4 Changes to 
http://wiki.audacityteam.org/wiki/Release_Process/Win#Copy_other_necessities_to_release_build_folder 
since we would now need to unzip the manual from code.google

I'll stop here as I'm sure there are other changes to be made to the 
release process, but it's not fully agreed that we should go this way.

And I'm not sure what the process for 2.0.1 will look like, or any 
idea if that is what it will be called or what will be in it!  A new 
frontier for us!

TTFN
Martyn

On 16/03/2012 22:16, Richard Ash wrote:
> There are at least two separate issues I want to differentiate, but I
> think we can do significantly better than at present. To my mind they
> are:
>
> 1. Delivering the off-line HTML manual to users who don't get it with an
> installer, without killing servers.
>
> 2. Providing stable on-line manuals for releases as opposed to a dynamic
> manual for development code
>
> 3. Updating the manual in 1. after release of binaries.
>
> My attitude to 1. is that what is needed is an archive of the same
> documentation that is in the installers, which has a _fixed_,
> _versioned_ URL, served by a _robust server platform_. To me this means
> creating one more file amongst the set we currently do for a release,
> which is named audacity-manual-<version>.zip and is uploaded onto Google
> code alongside the installers and source archives. The structure and
> content of this zip must be consistent, which means scripted creation
> (including the zipping).
>
> To save effort and potential consistency issues, we could decide that
> this must be produced before the installers are built (by running our
> fully-automated script on any suitable platform), and the help for the
> installers becomes an unpacked copy of the zip file.
>
> We can then link to this help file wherever we like, and where necessary
> links to older manual versions continue to be valid (e.g. in READMEs
> etc). It will be listed as a source archive into Linux distribution
> packaging scripts in the same way that the minsrc is, to package the
> manual for Linux distributions (where the manual package will depend on
> the version-matched Audacity package, keeping them in sync).
>
> I think the correct solution to 2. is to use the static HTML we generate
> for 1. and serve it from audacityteam.org, with all CGI turned off (in
> web server config file rather than .htaccess) for the directory tree
> (the directory it is served from should match the zip file name minus
> extension, so that the online copy also becomes a permanent, versioned,
> URL). This should be low-load to serve, because it doesn't have to go
> through PHP or touch the database.
>
> These should be the links which
> AudacityProject::OnManual()
> hit, which can be worked out from the #defines in Audacity.h (so you
> don't need arguments, it's done at compile time with some clever
> pre-processor stuff). This ensures that the online Manual in an old
> version of Audacity still looks like it did when the version was new,
> just as the downloaded ones do.
>
> We are already most of the way to having this with the "frozen" manual
> at http://manual.audacityteam.org/help/manual/ not being the wiki, but I
> would prefer that URL to be a redirect (temporary 302 I think) to
> http://manual.audacityteam.org/help/audacity-manual-2.0.0/
> with the same content. Then when the next release happens, we populate
> http://manual.audacityteam.org/help/audacity-manual-2.0.0/
> with the zip contents, and change the single redirect over. A simple
> HTML page somewhere can provide links to the (growing) list of old
> versions of the manual.
>
> Having thought this through, I think 3. is a mistake. I disagree with
> Martyn here - if we have a manual update that matters enough to push
> back, then it's a new release, because we need to rebuild the installers
> to make them consistent with the other manual distribution channels. I
> know this doesn't help the corporate stuck users, but it's unlikely they
> can install a new set of help files either. They can always be pointed
> to a more recent manual for specific improved documentation, whether
> that is on-line or off-line.
>
> In a wider picture, I would also venture that back-porting documentation
> changes to older versions manuals is, in the greater scheme of things, a
> waste of everybody here's time. Ultimately for high-churn stuff like
> this, use the main, online wiki site.
>
> Richard
>
>
> ------------------------------------------------------------------------------
> This SF email is sponsosred by:
> Try Windows Azure free for 90 days Click Here
> http://p.sf.net/sfu/sfd2d-msazure
> _______________________________________________
> audacity-devel mailing list
> aud...@li...
> https://lists.sourceforge.net/lists/listinfo/audacity-devel