Quantcast

Manual ZIP file packed incorrectly

classic Classic list List threaded Threaded
31 messages Options
12
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Manual ZIP file packed incorrectly

Stevethefiddle
Shouldn't the "index.html" page be inside the "manual" folder?
In the manual on FossHub, it isn't.
https://www.fosshub.com/Audacity.html

Steve

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Gale
Administrator
Yes whoever packaged it got it wrong. When unzipped, the
entire contents should be in a "manual" folder and that
"manual" folder should be in a "help" folder.

But under strict "no hotswapping" rules we can't fix it, so I
haven't done so.  I think strict interpretation would be silly
for the Manual, but James as 2.1.3 RM will have to rule on it.



Gale



On 9 May 2017 at 09:32, Steve the Fiddle <[hidden email]> wrote:

> Shouldn't the "index.html" page be inside the "manual" folder?
> In the manual on FossHub, it isn't.
> https://www.fosshub.com/Audacity.html
>
> Steve
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Stevethefiddle
On 9 May 2017 at 20:43, Gale Andrews <[hidden email]> wrote:
> Yes whoever packaged it got it wrong. When unzipped, the
> entire contents should be in a "manual" folder and that
> "manual" folder should be in a "help" folder.
>
> But under strict "no hotswapping" rules we can't fix it,  so I
> haven't done so.  I think strict interpretation would be silly


Yes, that would just be silly :-)
The manual on FossHub doesn't work with Audacity. Better that we fix
it than require every user that downloads it to fix it.

> for the Manual, but James as 2.1.3 RM will have to rule on it.

I don't believe it is a "release" issue any more. The release of
Audacity 2.1.3 has been and gone. Nevertheless, I'm sure that James
will agree that it needs to be fixed asap.

Steve

>
>
>
> Gale
>
>
>
> On 9 May 2017 at 09:32, Steve the Fiddle <[hidden email]> wrote:
>> Shouldn't the "index.html" page be inside the "manual" folder?
>> In the manual on FossHub, it isn't.
>> https://www.fosshub.com/Audacity.html
>>
>> Steve
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

James Crook
On 5/9/2017 9:08 PM, Steve the Fiddle wrote:

> On 9 May 2017 at 20:43, Gale Andrews <[hidden email]> wrote:
>> Yes whoever packaged it got it wrong. When unzipped, the
>> entire contents should be in a "manual" folder and that
>> "manual" folder should be in a "help" folder.
>>
>> But under strict "no hotswapping" rules we can't fix it,  so I
>> haven't done so.  I think strict interpretation would be silly
>
> Yes, that would just be silly :-)
> The manual on FossHub doesn't work with Audacity. Better that we fix
> it than require every user that downloads it to fix it.
>
>> for the Manual, but James as 2.1.3 RM will have to rule on it.
> I don't believe it is a "release" issue any more. The release of
> Audacity 2.1.3 has been and gone. Nevertheless, I'm sure that James
> will agree that it needs to be fixed asap.
The structure is the same as the structure that the script to pull the
manual creates.   Index.html, quick_ help.html and favicon.ico at the
top, then folders manual, man and m below.  What might be confusing is
that this is all typically installed to a path ./help/manual so the word
'manual' can appear twice in the path (to images).

It IS a false alarm.  The zip works as is, at least on Windows it does.

I agree it is not a 2.13 release manager issue anymore.

I disagree about hotfixing it without changing the version number. If it
were necessary to hotfix it, I think calling it 2.1.3a could make sense.

--James.



>
> Steve
>
>>
>>
>> Gale
>>
>>
>>
>> On 9 May 2017 at 09:32, Steve the Fiddle <[hidden email]> wrote:
>>> Shouldn't the "index.html" page be inside the "manual" folder?
>>> In the manual on FossHub, it isn't.
>>> https://www.fosshub.com/Audacity.html
>>>
>>> Steve
>>>
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> [hidden email]
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
>


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Stevethefiddle
On 9 May 2017 at 21:53, James Crook <[hidden email]> wrote:

> On 5/9/2017 9:08 PM, Steve the Fiddle wrote:
>> On 9 May 2017 at 20:43, Gale Andrews <[hidden email]> wrote:
>>> Yes whoever packaged it got it wrong. When unzipped, the
>>> entire contents should be in a "manual" folder and that
>>> "manual" folder should be in a "help" folder.
>>>
>>> But under strict "no hotswapping" rules we can't fix it,  so I
>>> haven't done so.  I think strict interpretation would be silly
>>
>> Yes, that would just be silly :-)
>> The manual on FossHub doesn't work with Audacity. Better that we fix
>> it than require every user that downloads it to fix it.
>>
>>> for the Manual, but James as 2.1.3 RM will have to rule on it.
>> I don't believe it is a "release" issue any more. The release of
>> Audacity 2.1.3 has been and gone. Nevertheless, I'm sure that James
>> will agree that it needs to be fixed asap.
> The structure is the same as the structure that the script to pull the
> manual creates.   Index.html, quick_ help.html and favicon.ico at the
> top, then folders manual, man and m below.  What might be confusing is
> that this is all typically installed to a path ./help/manual so the word
> 'manual' can appear twice in the path (to images).
>
> It IS a false alarm.  The zip works as is, at least on Windows it does.

It's a mess on Linux.

The link in the Help menu goes to here:
http://manual.audacityteam.org/man/unzipping_the_manual.html

The instructions are wrong because the file is not
"audacity-manual-2.1.3.zip" (it's "audacity-help-2.1.3.zip").

If the user works that out, they end up with a load of files and
folders in their .../share/audacity/ folder instead of in
.../share/audacity/help

If the user works that out and puts them into .../share/audacity/help/
it still doesn't work because Audacity is looking for index.html in
../share/audacity/help/manual/index.html

Steve

>
> I agree it is not a 2.13 release manager issue anymore.
>
> I disagree about hotfixing it without changing the version number. If it
> were necessary to hotfix it, I think calling it 2.1.3a could make sense.
>
> --James.
>
>
>
>>
>> Steve
>>
>>>
>>>
>>> Gale
>>>
>>>
>>>
>>> On 9 May 2017 at 09:32, Steve the Fiddle <[hidden email]> wrote:
>>>> Shouldn't the "index.html" page be inside the "manual" folder?
>>>> In the manual on FossHub, it isn't.
>>>> https://www.fosshub.com/Audacity.html
>>>>
>>>> Steve
>>>>
>>>> ------------------------------------------------------------------------------
>>>> Check out the vibrant tech community on one of the world's most
>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>> _______________________________________________
>>>> Audacity-quality mailing list
>>>> [hidden email]
>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> [hidden email]
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>
>>
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Stevethefiddle
On 9 May 2017 at 22:50, Steve the Fiddle <[hidden email]> wrote:

> On 9 May 2017 at 21:53, James Crook <[hidden email]> wrote:
>> On 5/9/2017 9:08 PM, Steve the Fiddle wrote:
>>> On 9 May 2017 at 20:43, Gale Andrews <[hidden email]> wrote:
>>>> Yes whoever packaged it got it wrong. When unzipped, the
>>>> entire contents should be in a "manual" folder and that
>>>> "manual" folder should be in a "help" folder.
>>>>
>>>> But under strict "no hotswapping" rules we can't fix it,  so I
>>>> haven't done so.  I think strict interpretation would be silly
>>>
>>> Yes, that would just be silly :-)
>>> The manual on FossHub doesn't work with Audacity. Better that we fix
>>> it than require every user that downloads it to fix it.
>>>
>>>> for the Manual, but James as 2.1.3 RM will have to rule on it.
>>> I don't believe it is a "release" issue any more. The release of
>>> Audacity 2.1.3 has been and gone. Nevertheless, I'm sure that James
>>> will agree that it needs to be fixed asap.
>> The structure is the same as the structure that the script to pull the
>> manual creates.   Index.html, quick_ help.html and favicon.ico at the
>> top, then folders manual, man and m below.  What might be confusing is
>> that this is all typically installed to a path ./help/manual so the word
>> 'manual' can appear twice in the path (to images).
>>
>> It IS a false alarm.  The zip works as is, at least on Windows it does.
>
> It's a mess on Linux.
>
> The link in the Help menu goes to here:
> http://manual.audacityteam.org/man/unzipping_the_manual.html
>
> The instructions are wrong because the file is not
> "audacity-manual-2.1.3.zip" (it's "audacity-help-2.1.3.zip").
>
> If the user works that out, they end up with a load of files and
> folders in their .../share/audacity/ folder instead of in
> .../share/audacity/help
>
> If the user works that out and puts them into .../share/audacity/help/
> it still doesn't work because Audacity is looking for index.html in
> ../share/audacity/help/manual/index.html


Sorry, I just read that back, and I didn't intend it to sound so
harsh/critical, but it is very messed up for Linux users, and imo
opinion we need to fix it as soon as possible, but also work out what
went wrong.

Steve

>
> Steve
>
>>
>> I agree it is not a 2.13 release manager issue anymore.
>>
>> I disagree about hotfixing it without changing the version number. If it
>> were necessary to hotfix it, I think calling it 2.1.3a could make sense.
>>
>> --James.
>>
>>
>>
>>>
>>> Steve
>>>
>>>>
>>>>
>>>> Gale
>>>>
>>>>
>>>>
>>>> On 9 May 2017 at 09:32, Steve the Fiddle <[hidden email]> wrote:
>>>>> Shouldn't the "index.html" page be inside the "manual" folder?
>>>>> In the manual on FossHub, it isn't.
>>>>> https://www.fosshub.com/Audacity.html
>>>>>
>>>>> Steve
>>>>>
>>>>> ------------------------------------------------------------------------------
>>>>> Check out the vibrant tech community on one of the world's most
>>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>>> _______________________________________________
>>>>> Audacity-quality mailing list
>>>>> [hidden email]
>>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>> ------------------------------------------------------------------------------
>>>> Check out the vibrant tech community on one of the world's most
>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>> _______________________________________________
>>>> Audacity-quality mailing list
>>>> [hidden email]
>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> [hidden email]
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>
>>>
>>
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Gale
Administrator
James, it's broken for all users who intend to locate the
standalone zipped Manual from within Audacity.

It would be good if a script could automate what is required,
but the "zipping" part of
http://wiki.audacityteam.org/wiki/Create_Local_Manual
was not followed as it should have been (it's a clear part
of http://wiki.audacityteam.org/wiki/Release_Process).

If the corrected ZIP file needs to be renamed then
http://manual.audacityteam.org/man/unzipping_the_manual.html.

would have to change its link (that's the online copy of the
released Manual).  However it's a packaging change only, not
a change of content.

If it's not James's decision on hotswap or not, then whose is it?
It's 2.1.3 release and James was 2.1.3 RM.


Gale


On 9 May 2017 at 23:04, Steve the Fiddle <[hidden email]> wrote:

> On 9 May 2017 at 22:50, Steve the Fiddle <[hidden email]> wrote:
>> On 9 May 2017 at 21:53, James Crook <[hidden email]> wrote:
>>> On 5/9/2017 9:08 PM, Steve the Fiddle wrote:
>>>> On 9 May 2017 at 20:43, Gale Andrews <[hidden email]> wrote:
>>>>> Yes whoever packaged it got it wrong. When unzipped, the
>>>>> entire contents should be in a "manual" folder and that
>>>>> "manual" folder should be in a "help" folder.
>>>>>
>>>>> But under strict "no hotswapping" rules we can't fix it,  so I
>>>>> haven't done so.  I think strict interpretation would be silly
>>>>
>>>> Yes, that would just be silly :-)
>>>> The manual on FossHub doesn't work with Audacity. Better that we fix
>>>> it than require every user that downloads it to fix it.
>>>>
>>>>> for the Manual, but James as 2.1.3 RM will have to rule on it.
>>>> I don't believe it is a "release" issue any more. The release of
>>>> Audacity 2.1.3 has been and gone. Nevertheless, I'm sure that James
>>>> will agree that it needs to be fixed asap.
>>> The structure is the same as the structure that the script to pull the
>>> manual creates.   Index.html, quick_ help.html and favicon.ico at the
>>> top, then folders manual, man and m below.  What might be confusing is
>>> that this is all typically installed to a path ./help/manual so the word
>>> 'manual' can appear twice in the path (to images).
>>>
>>> It IS a false alarm.  The zip works as is, at least on Windows it does.
>>
>> It's a mess on Linux.
>>
>> The link in the Help menu goes to here:
>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>
>> The instructions are wrong because the file is not
>> "audacity-manual-2.1.3.zip" (it's "audacity-help-2.1.3.zip").
>>
>> If the user works that out, they end up with a load of files and
>> folders in their .../share/audacity/ folder instead of in
>> .../share/audacity/help
>>
>> If the user works that out and puts them into .../share/audacity/help/
>> it still doesn't work because Audacity is looking for index.html in
>> ../share/audacity/help/manual/index.html
>
>
> Sorry, I just read that back, and I didn't intend it to sound so
> harsh/critical, but it is very messed up for Linux users, and imo
> opinion we need to fix it as soon as possible, but also work out what
> went wrong.
>
> Steve
>
>>
>> Steve
>>
>>>
>>> I agree it is not a 2.13 release manager issue anymore.
>>>
>>> I disagree about hotfixing it without changing the version number. If it
>>> were necessary to hotfix it, I think calling it 2.1.3a could make sense.
>>>
>>> --James.
>>>
>>>
>>>
>>>>
>>>> Steve
>>>>
>>>>>
>>>>>
>>>>> Gale
>>>>>
>>>>>
>>>>>
>>>>> On 9 May 2017 at 09:32, Steve the Fiddle <[hidden email]> wrote:
>>>>>> Shouldn't the "index.html" page be inside the "manual" folder?
>>>>>> In the manual on FossHub, it isn't.
>>>>>> https://www.fosshub.com/Audacity.html
>>>>>>
>>>>>> Steve
>>>>>>
>>>>>> ------------------------------------------------------------------------------
>>>>>> Check out the vibrant tech community on one of the world's most
>>>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>>>> _______________________________________________
>>>>>> Audacity-quality mailing list
>>>>>> [hidden email]
>>>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>>> ------------------------------------------------------------------------------
>>>>> Check out the vibrant tech community on one of the world's most
>>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>>> _______________________________________________
>>>>> Audacity-quality mailing list
>>>>> [hidden email]
>>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>> ------------------------------------------------------------------------------
>>>> Check out the vibrant tech community on one of the world's most
>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>> _______________________________________________
>>>> Audacity-quality mailing list
>>>> [hidden email]
>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>>
>>>>
>>>
>>>
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> [hidden email]
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Stevethefiddle
On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
> James, it's broken for all users who intend to locate the
> standalone zipped Manual from within Audacity.
>
> It would be good if a script could automate what is required,
> but the "zipping" part of
> http://wiki.audacityteam.org/wiki/Create_Local_Manual
> was not followed as it should have been (it's a clear part
> of http://wiki.audacityteam.org/wiki/Release_Process).

I think we can make the instruction clearer.
On Linux (Xubuntu) it is necessary to move the "manual" folder
(downloaded with the wiki2htm.sh script) into an empty "help" folder
before zipping it (with "Archive Manager").

>
> If the corrected ZIP file needs to be renamed then
> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>
> would have to change its link (that's the online copy of the
> released Manual).  However it's a packaging change only, not
> a change of content.

The 'packaging' (the zipping process) is certainly wrong.
Are the contents correct? I notice that the index page says:

"Audacity Manual Contents
>From Audacity Development Manual"

I've not seen the Windows version, but if that's the same, then I
think we need to stick with that even though it looks a bit weird.

What do we call the new package?
How about: "audacity-manual-2.1.3-1.zip"

>
> If it's not James's decision on hotswap or not, then whose is it?
> It's 2.1.3 release and James was 2.1.3 RM.

If there is no disagreement about the need for it to be done, then
there is no decision to make other than how we go about fixing it.

Steve

>
>
> Gale
>
>
> On 9 May 2017 at 23:04, Steve the Fiddle <[hidden email]> wrote:
>> On 9 May 2017 at 22:50, Steve the Fiddle <[hidden email]> wrote:
>>> On 9 May 2017 at 21:53, James Crook <[hidden email]> wrote:
>>>> On 5/9/2017 9:08 PM, Steve the Fiddle wrote:
>>>>> On 9 May 2017 at 20:43, Gale Andrews <[hidden email]> wrote:
>>>>>> Yes whoever packaged it got it wrong. When unzipped, the
>>>>>> entire contents should be in a "manual" folder and that
>>>>>> "manual" folder should be in a "help" folder.
>>>>>>
>>>>>> But under strict "no hotswapping" rules we can't fix it,  so I
>>>>>> haven't done so.  I think strict interpretation would be silly
>>>>>
>>>>> Yes, that would just be silly :-)
>>>>> The manual on FossHub doesn't work with Audacity. Better that we fix
>>>>> it than require every user that downloads it to fix it.
>>>>>
>>>>>> for the Manual, but James as 2.1.3 RM will have to rule on it.
>>>>> I don't believe it is a "release" issue any more. The release of
>>>>> Audacity 2.1.3 has been and gone. Nevertheless, I'm sure that James
>>>>> will agree that it needs to be fixed asap.
>>>> The structure is the same as the structure that the script to pull the
>>>> manual creates.   Index.html, quick_ help.html and favicon.ico at the
>>>> top, then folders manual, man and m below.  What might be confusing is
>>>> that this is all typically installed to a path ./help/manual so the word
>>>> 'manual' can appear twice in the path (to images).
>>>>
>>>> It IS a false alarm.  The zip works as is, at least on Windows it does.
>>>
>>> It's a mess on Linux.
>>>
>>> The link in the Help menu goes to here:
>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>>
>>> The instructions are wrong because the file is not
>>> "audacity-manual-2.1.3.zip" (it's "audacity-help-2.1.3.zip").
>>>
>>> If the user works that out, they end up with a load of files and
>>> folders in their .../share/audacity/ folder instead of in
>>> .../share/audacity/help
>>>
>>> If the user works that out and puts them into .../share/audacity/help/
>>> it still doesn't work because Audacity is looking for index.html in
>>> ../share/audacity/help/manual/index.html
>>
>>
>> Sorry, I just read that back, and I didn't intend it to sound so
>> harsh/critical, but it is very messed up for Linux users, and imo
>> opinion we need to fix it as soon as possible, but also work out what
>> went wrong.
>>
>> Steve
>>
>>>
>>> Steve
>>>
>>>>
>>>> I agree it is not a 2.13 release manager issue anymore.
>>>>
>>>> I disagree about hotfixing it without changing the version number. If it
>>>> were necessary to hotfix it, I think calling it 2.1.3a could make sense.
>>>>
>>>> --James.
>>>>
>>>>
>>>>
>>>>>
>>>>> Steve
>>>>>
>>>>>>
>>>>>>
>>>>>> Gale
>>>>>>
>>>>>>
>>>>>>
>>>>>> On 9 May 2017 at 09:32, Steve the Fiddle <[hidden email]> wrote:
>>>>>>> Shouldn't the "index.html" page be inside the "manual" folder?
>>>>>>> In the manual on FossHub, it isn't.
>>>>>>> https://www.fosshub.com/Audacity.html
>>>>>>>
>>>>>>> Steve
>>>>>>>
>>>>>>> ------------------------------------------------------------------------------

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Gale
Administrator
On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:

> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>> James, it's broken for all users who intend to locate the
>> standalone zipped Manual from within Audacity.
>>
>> It would be good if a script could automate what is required,
>> but the "zipping" part of
>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>> was not followed as it should have been (it's a clear part
>> of http://wiki.audacityteam.org/wiki/Release_Process).
>
> I think we can make the instruction clearer.
> On Linux (Xubuntu) it is necessary to move the "manual" folder
> (downloaded with the wiki2htm.sh script) into an empty "help" folder
> before zipping it (with "Archive Manager").

Surely all a developer on any platform needs to know is the
structure that is wanted?


>> If the corrected ZIP file needs to be renamed then
>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>
>> would have to change its link (that's the online copy of the
>> released Manual).  However it's a packaging change only, not
>> a change of content.
>
> The 'packaging' (the zipping process) is certainly wrong.
> Are the contents correct? I notice that the index page says:
>
> "Audacity Manual Contents
> >From Audacity Development Manual"

As I said before, that happens because the released Manual
is dumped from the development Manual. When users visit
the development Manual, we want the site title to say
"Audacity Development Manual" so they can distinguish it
from the online released Manual.

So when we dump, we change the alphamanual site title
to "Audacity Manual" and while we wait to see if the RC will
pass, we change it back to "Audacity Development Manual" .
When we have a protracted release with many RCs, it's
easy to forget to change the alphamanual site title each time
the Manual is dumped.

The contents are correct apart from that.

I really hope Buanzo will succeed with the Manual clone
because I assume that will solve this site title problem. :=)


> I've not seen the Windows version, but if that's the same, then I
> think we need to stick with that even though it looks a bit weird.

Yes.

> What do we call the new package?
> How about: "audacity-manual-2.1.3-1.zip"
>
>>
>> If it's not James's decision on hotswap or not, then whose is it?
>> It's 2.1.3 release and James was 2.1.3 RM.
>
> If there is no disagreement about the need for it to be done, then
> there is no decision to make other than how we go about fixing it.

Just repackage it correctly with a new file name, as far as I am
concerned.


Gale

>
> Steve
>
>>
>>
>> Gale
>>
>>
>> On 9 May 2017 at 23:04, Steve the Fiddle <[hidden email]> wrote:
>>> On 9 May 2017 at 22:50, Steve the Fiddle <[hidden email]> wrote:
>>>> On 9 May 2017 at 21:53, James Crook <[hidden email]> wrote:
>>>>> On 5/9/2017 9:08 PM, Steve the Fiddle wrote:
>>>>>> On 9 May 2017 at 20:43, Gale Andrews <[hidden email]> wrote:
>>>>>>> Yes whoever packaged it got it wrong. When unzipped, the
>>>>>>> entire contents should be in a "manual" folder and that
>>>>>>> "manual" folder should be in a "help" folder.
>>>>>>>
>>>>>>> But under strict "no hotswapping" rules we can't fix it,  so I
>>>>>>> haven't done so.  I think strict interpretation would be silly
>>>>>>
>>>>>> Yes, that would just be silly :-)
>>>>>> The manual on FossHub doesn't work with Audacity. Better that we fix
>>>>>> it than require every user that downloads it to fix it.
>>>>>>
>>>>>>> for the Manual, but James as 2.1.3 RM will have to rule on it.
>>>>>> I don't believe it is a "release" issue any more. The release of
>>>>>> Audacity 2.1.3 has been and gone. Nevertheless, I'm sure that James
>>>>>> will agree that it needs to be fixed asap.
>>>>> The structure is the same as the structure that the script to pull the
>>>>> manual creates.   Index.html, quick_ help.html and favicon.ico at the
>>>>> top, then folders manual, man and m below.  What might be confusing is
>>>>> that this is all typically installed to a path ./help/manual so the word
>>>>> 'manual' can appear twice in the path (to images).
>>>>>
>>>>> It IS a false alarm.  The zip works as is, at least on Windows it does.
>>>>
>>>> It's a mess on Linux.
>>>>
>>>> The link in the Help menu goes to here:
>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>>>
>>>> The instructions are wrong because the file is not
>>>> "audacity-manual-2.1.3.zip" (it's "audacity-help-2.1.3.zip").
>>>>
>>>> If the user works that out, they end up with a load of files and
>>>> folders in their .../share/audacity/ folder instead of in
>>>> .../share/audacity/help
>>>>
>>>> If the user works that out and puts them into .../share/audacity/help/
>>>> it still doesn't work because Audacity is looking for index.html in
>>>> ../share/audacity/help/manual/index.html
>>>
>>>
>>> Sorry, I just read that back, and I didn't intend it to sound so
>>> harsh/critical, but it is very messed up for Linux users, and imo
>>> opinion we need to fix it as soon as possible, but also work out what
>>> went wrong.
>>>
>>> Steve
>>>
>>>>
>>>> Steve
>>>>
>>>>>
>>>>> I agree it is not a 2.13 release manager issue anymore.
>>>>>
>>>>> I disagree about hotfixing it without changing the version number. If it
>>>>> were necessary to hotfix it, I think calling it 2.1.3a could make sense.
>>>>>
>>>>> --James.
>>>>>
>>>>>
>>>>>
>>>>>>
>>>>>> Steve
>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Gale
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On 9 May 2017 at 09:32, Steve the Fiddle <[hidden email]> wrote:
>>>>>>>> Shouldn't the "index.html" page be inside the "manual" folder?
>>>>>>>> In the manual on FossHub, it isn't.
>>>>>>>> https://www.fosshub.com/Audacity.html
>>>>>>>>
>>>>>>>> Steve
>>>>>>>>
>>>>>>>> ------------------------------------------------------------------------------
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

James Crook
On 5/10/2017 2:12 AM, Gale Andrews wrote:

> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>> James, it's broken for all users who intend to locate the
>>> standalone zipped Manual from within Audacity.
>>>
>>> It would be good if a script could automate what is required,
>>> but the "zipping" part of
>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>> was not followed as it should have been (it's a clear part
>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>> I think we can make the instruction clearer.
>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>> before zipping it (with "Archive Manager").
> Surely all a developer on any platform needs to know is the
> structure that is wanted?
I think the instructions on installing the manual (what paths to end up
with after unzipping) and building the manual (the zipping part) both
could be improved.  My install of RC3 (from innosetup) has the manual in
the correct position with the correct name, (i.e. not development manual).

Why do we have a ./help/manual/ in the path and not just ./help or just
./manual?  It seems an extra level that serves no purpose and just makes
manual installation harder.


>
>>> If the corrected ZIP file needs to be renamed then
>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>
>>> would have to change its link (that's the online copy of the
>>> released Manual).  However it's a packaging change only, not
>>> a change of content.
>> The 'packaging' (the zipping process) is certainly wrong.
>> Are the contents correct? I notice that the index page says:
>>
>> "Audacity Manual Contents
>> >From Audacity Development Manual"
> As I said before, that happens because the released Manual
> is dumped from the development Manual. When users visit
> the development Manual, we want the site title to say
> "Audacity Development Manual" so they can distinguish it
> from the online released Manual.
>
> So when we dump, we change the alphamanual site title
> to "Audacity Manual" and while we wait to see if the RC will
> pass, we change it back to "Audacity Development Manual" .
> When we have a protracted release with many RCs, it's
> easy to forget to change the alphamanual site title each time
> the Manual is dumped.
>
> The contents are correct apart from that.
I actually did that change to the html after the manual was pulled. We
could incorporate it in the script that fetches the manual.

> I really hope Buanzo will succeed with the Manual clone
> because I assume that will solve this site title problem. :=)
>
>
>> I've not seen the Windows version, but if that's the same, then I
>> think we need to stick with that even though it looks a bit weird.
> Yes.
Why not fix it?  If there is a new version of the file to download
shouldn't we fix that too?

>
>> What do we call the new package?
>> How about: "audacity-manual-2.1.3-1.zip"
>>
>>> If it's not James's decision on hotswap or not, then whose is it?
>>> It's 2.1.3 release and James was 2.1.3 RM.
>> If there is no disagreement about the need for it to be done, then
>> there is no decision to make other than how we go about fixing it.
> Just repackage it correctly with a new file name, as far as I am
> concerned.
>
>
> Gale

We could fix/clarify the instructions at
http://manual.audacityteam.org/man/unzipping_the_manual.html
and that would work just as well as a fix.

I would presume we will shorten the install path for 2.2.0 help and
clarify those instructions for 2.2.0 to say where the help files should
end up.

Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
users who just fetch and unzip it have some instructions on how to make
Audacity find it.

I took my RM-is-God hat off after 2.1.3 release was announced, so you
shouldn't be waiting on me for approval.  I'd imagine most users who
download the manual separately are accessing it directly rather than
from within Audacity - and also that the vast majority of linux users
use the manual on line.

--James.




------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Stevethefiddle
On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:

> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>> James, it's broken for all users who intend to locate the
>>>> standalone zipped Manual from within Audacity.
>>>>
>>>> It would be good if a script could automate what is required,
>>>> but the "zipping" part of
>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>> was not followed as it should have been (it's a clear part
>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>> I think we can make the instruction clearer.
>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>> before zipping it (with "Archive Manager").
>> Surely all a developer on any platform needs to know is the
>> structure that is wanted?
> I think the instructions on installing the manual (what paths to end up
> with after unzipping) and building the manual (the zipping part) both
> could be improved.  My install of RC3 (from innosetup) has the manual in
> the correct position with the correct name, (i.e. not development manual).
>
> Why do we have a ./help/manual/ in the path and not just ./help or just
> ./manual?  It seems an extra level that serves no purpose and just makes
> manual installation harder.

I agree, the path to the manual is overly complex. I suspect that it
came about due to differences in archive extraction apps, with some
extracting the archive contents directly into the specified location,
and others extracting into a folder in the specified direction. What
we want to avoid is spewing a mass of files into a location where
other (non-manual) files exist.

My guess is that index.html and quick_help.html are outside of the
main "manual" folder so that the can be found easily by anyone wanting
to access the manual directly (rather than from Audacity).

>
>
>>
>>>> If the corrected ZIP file needs to be renamed then
>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>
>>>> would have to change its link (that's the online copy of the
>>>> released Manual).  However it's a packaging change only, not
>>>> a change of content.
>>> The 'packaging' (the zipping process) is certainly wrong.
>>> Are the contents correct? I notice that the index page says:
>>>
>>> "Audacity Manual Contents
>>> >From Audacity Development Manual"
>> As I said before, that happens because the released Manual
>> is dumped from the development Manual. When users visit
>> the development Manual, we want the site title to say
>> "Audacity Development Manual" so they can distinguish it
>> from the online released Manual.
>>
>> So when we dump, we change the alphamanual site title
>> to "Audacity Manual" and while we wait to see if the RC will
>> pass, we change it back to "Audacity Development Manual" .
>> When we have a protracted release with many RCs, it's
>> easy to forget to change the alphamanual site title each time
>> the Manual is dumped.
>>
>> The contents are correct apart from that.
> I actually did that change to the html after the manual was pulled.

So does the in-app Windows EXE / Mac DMG manual say "From the
Development Manual"?

> We
> could incorporate it in the script that fetches the manual.
>
>> I really hope Buanzo will succeed with the Manual clone
>> because I assume that will solve this site title problem. :=)
>>
>>
>>> I've not seen the Windows version, but if that's the same, then I
>>> think we need to stick with that even though it looks a bit weird.
>> Yes.
> Why not fix it?  If there is a new version of the file to download
> shouldn't we fix that too?

I would hope that we can avoid going through a "release process" for a
new version of the manual.
Once you say "we'll just fix this little bit", then surely it makes
sense to also fix "that little bit", and perhaps "that other little
bit"...

>From a support point of view, it is much 'cleaner' if all versions of
"the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
favour of 'only' repacking the manual, assuming that the manual in the
EXE / DMG bundles are the same as the current ZIP'd manual.

If the manual in the EXE / DMG are different to the current ZIP'd
version, then I think we should package the EXE / DMG version as the
new ZIP.

>
>>
>>> What do we call the new package?
>>> How about: "audacity-manual-2.1.3-1.zip"

Assuming no changes to the content of the manual, I'm +1 for naming
it: "audacity-manual-2.1.3-1.zip"

>>>
>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>> If there is no disagreement about the need for it to be done, then
>>> there is no decision to make other than how we go about fixing it.
>> Just repackage it correctly with a new file name, as far as I am
>> concerned.
>>
>>
>> Gale
>
> We could fix/clarify the instructions at
> http://manual.audacityteam.org/man/unzipping_the_manual.html
> and that would work just as well as a fix.

Not as good a fix, because there's a million copies of the manual in the wild.


>
> I would presume we will shorten the install path for 2.2.0 help and
> clarify those instructions for 2.2.0 to say where the help files should
> end up.

+1

>
> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
> users who just fetch and unzip it have some instructions on how to make
> Audacity find it.

+1
or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).

>
> I took my RM-is-God hat off after 2.1.3 release was announced, so you
> shouldn't be waiting on me for approval.  I'd imagine most users who
> download the manual separately are accessing it directly rather than
> from within Audacity - and also that the vast majority of linux users
> use the manual on line.

Looks to me like we need to do more to encourage users to use the manual ;-)

As a regular user of open source software, our manual really is a huge
and fantastic selling point for Audacity. History is littered with
software that died through lack of good documentation. We should make
much of it.

Steve

>
> --James.
>

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

James Crook
On 5/10/2017 10:25 AM, Steve the Fiddle wrote:

> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>>> James, it's broken for all users who intend to locate the
>>>>> standalone zipped Manual from within Audacity.
>>>>>
>>>>> It would be good if a script could automate what is required,
>>>>> but the "zipping" part of
>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>>> was not followed as it should have been (it's a clear part
>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>>> I think we can make the instruction clearer.
>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>>> before zipping it (with "Archive Manager").
>>> Surely all a developer on any platform needs to know is the
>>> structure that is wanted?
>> I think the instructions on installing the manual (what paths to end up
>> with after unzipping) and building the manual (the zipping part) both
>> could be improved.  My install of RC3 (from innosetup) has the manual in
>> the correct position with the correct name, (i.e. not development manual).
>>
>> Why do we have a ./help/manual/ in the path and not just ./help or just
>> ./manual?  It seems an extra level that serves no purpose and just makes
>> manual installation harder.
> I agree, the path to the manual is overly complex. I suspect that it
> came about due to differences in archive extraction apps, with some
> extracting the archive contents directly into the specified location,
> and others extracting into a folder in the specified direction. What
> we want to avoid is spewing a mass of files into a location where
> other (non-manual) files exist.
>
> My guess is that index.html and quick_help.html are outside of the
> main "manual" folder so that the can be found easily by anyone wanting
> to access the manual directly (rather than from Audacity).
>
>>
>>>>> If the corrected ZIP file needs to be renamed then
>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>>
>>>>> would have to change its link (that's the online copy of the
>>>>> released Manual).  However it's a packaging change only, not
>>>>> a change of content.
>>>> The 'packaging' (the zipping process) is certainly wrong.
>>>> Are the contents correct? I notice that the index page says:
>>>>
>>>> "Audacity Manual Contents
>>>> >From Audacity Development Manual"
>>> As I said before, that happens because the released Manual
>>> is dumped from the development Manual. When users visit
>>> the development Manual, we want the site title to say
>>> "Audacity Development Manual" so they can distinguish it
>>> from the online released Manual.
>>>
>>> So when we dump, we change the alphamanual site title
>>> to "Audacity Manual" and while we wait to see if the RC will
>>> pass, we change it back to "Audacity Development Manual" .
>>> When we have a protracted release with many RCs, it's
>>> easy to forget to change the alphamanual site title each time
>>> the Manual is dumped.
>>>
>>> The contents are correct apart from that.
>> I actually did that change to the html after the manual was pulled.
> So does the in-app Windows EXE / Mac DMG manual say "From the
> Development Manual"?
>
>> We
>> could incorporate it in the script that fetches the manual.
>>
>>> I really hope Buanzo will succeed with the Manual clone
>>> because I assume that will solve this site title problem. :=)
>>>
>>>
>>>> I've not seen the Windows version, but if that's the same, then I
>>>> think we need to stick with that even though it looks a bit weird.
>>> Yes.
>> Why not fix it?  If there is a new version of the file to download
>> shouldn't we fix that too?
> I would hope that we can avoid going through a "release process" for a
> new version of the manual.

Sorry!  Lack of clarity over 'it'.
I meant that IF the zip says development manual, then we should fix that
too, if we decide we do need to issue a new zip of the manual. Am not
suggesting re-releasing 2.1.3 exes/installers.

> Once you say "we'll just fix this little bit", then surely it makes
> sense to also fix "that little bit", and perhaps "that other little
> bit"...
>
> >From a support point of view, it is much 'cleaner' if all versions of
> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
> favour of 'only' repacking the manual, assuming that the manual in the
> EXE / DMG bundles are the same as the current ZIP'd manual.
>
> If the manual in the EXE / DMG are different to the current ZIP'd
> version, then I think we should package the EXE / DMG version as the
> new ZIP.
>
>>>> What do we call the new package?
>>>> How about: "audacity-manual-2.1.3-1.zip"
> Assuming no changes to the content of the manual, I'm +1 for naming
> it: "audacity-manual-2.1.3-1.zip"
>
>>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>>> If there is no disagreement about the need for it to be done, then
>>>> there is no decision to make other than how we go about fixing it.
>>> Just repackage it correctly with a new file name, as far as I am
>>> concerned.
>>>
>>>
>>> Gale
>> We could fix/clarify the instructions at
>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>> and that would work just as well as a fix.
> Not as good a fix, because there's a million copies of the manual in the wild.
>
>
>> I would presume we will shorten the install path for 2.2.0 help and
>> clarify those instructions for 2.2.0 to say where the help files should
>> end up.
> +1
>
>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
>> users who just fetch and unzip it have some instructions on how to make
>> Audacity find it.
> +1
> or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).
>
>> I took my RM-is-God hat off after 2.1.3 release was announced, so you
>> shouldn't be waiting on me for approval.  I'd imagine most users who
>> download the manual separately are accessing it directly rather than
>> from within Audacity - and also that the vast majority of linux users
>> use the manual on line.
> Looks to me like we need to do more to encourage users to use the manual ;-)
>
> As a regular user of open source software, our manual really is a huge
> and fantastic selling point for Audacity. History is littered with
> software that died through lack of good documentation. We should make
> much of it.
>
> Steve
>
>> --James.
>>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
>


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Gale
Administrator
In reply to this post by Stevethefiddle
On 10 May 2017 at 10:25, Steve the Fiddle <[hidden email]> wrote:

> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>>> James, it's broken for all users who intend to locate the
>>>>> standalone zipped Manual from within Audacity.
>>>>>
>>>>> It would be good if a script could automate what is required,
>>>>> but the "zipping" part of
>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>>> was not followed as it should have been (it's a clear part
>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>>> I think we can make the instruction clearer.
>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>>> before zipping it (with "Archive Manager").
>>> Surely all a developer on any platform needs to know is the
>>> structure that is wanted?
>> I think the instructions on installing the manual (what paths to end up
>> with after unzipping) and building the manual (the zipping part) both
>> could be improved.  My install of RC3 (from innosetup) has the manual in
>> the correct position with the correct name, (i.e. not development manual).
>>
>> Why do we have a ./help/manual/ in the path and not just ./help or just
>> ./manual?  It seems an extra level that serves no purpose and just makes
>> manual installation harder.
>
> I agree, the path to the manual is overly complex. I suspect that it
> came about due to differences in archive extraction apps, with some
> extracting the archive contents directly into the specified location,
> and others extracting into a folder in the specified direction.

Those differences seem to me to be compelling reason not to
"improve" the developer instructions on building the Manual by
giving per app instructions. .

The developer can choose his app on his particular OS to package
the zip, knowing that he has to produce a ZIP that:

   "should produce a "help" folder with the "manual" folder inside that".

All you need to do (for example) is to right-click the ZIP file you
packaged > 7-Zip > Open Archive and check you are looking at the
"help" folder.


> what we want to avoid is spewing a mass of files into a location where
> other (non-manual) files exist.
>
> My guess is that index.html and quick_help.html are outside of the
> main "manual" folder so that the can be found easily by anyone wanting
> to access the manual directly (rather than from Audacity).

>>>>> If the corrected ZIP file needs to be renamed then
>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>>
>>>>> would have to change its link (that's the online copy of the
>>>>> released Manual).  However it's a packaging change only, not
>>>>> a change of content.
>>>> The 'packaging' (the zipping process) is certainly wrong.
>>>> Are the contents correct? I notice that the index page says:
>>>>
>>>> "Audacity Manual Contents
>>>> >From Audacity Development Manual"
>>> As I said before, that happens because the released Manual
>>> is dumped from the development Manual. When users visit
>>> the development Manual, we want the site title to say
>>> "Audacity Development Manual" so they can distinguish it
>>> from the online released Manual.
>>>
>>> So when we dump, we change the alphamanual site title
>>> to "Audacity Manual" and while we wait to see if the RC will
>>> pass, we change it back to "Audacity Development Manual" .
>>> When we have a protracted release with many RCs, it's
>>> easy to forget to change the alphamanual site title each time
>>> the Manual is dumped.
>>>
>>> The contents are correct apart from that.
>> I actually did that change to the html after the manual was pulled.

How did you do that?  I know no way to do that, once the files are
dumped, except text replace in all the files.

I assumed we were trying to avoid "content changes". If someone
downloaded the ZIP already, deleted it by accident then redownloads
it with the page titles changed to "Audacity Manual", might that not
be confusing? Is it the same Manual they had before?


> So does the in-app Windows EXE / Mac DMG manual say "From the
> Development Manual"?

On Windows the 2.1.3 EXE installer produces page titles that say
"Audacity Development Manual". I am 99% certain that Mac is the
same, from memory.


>> We
>> could incorporate it in the script that fetches the manual.
>>
>>> I really hope Buanzo will succeed with the Manual clone
>>> because I assume that will solve this site title problem. :=)
>>>
>>>
>>>> I've not seen the Windows version, but if that's the same, then I
>>>> think we need to stick with that even though it looks a bit weird.
>>> Yes.
>> Why not fix it?

ROI could be another reason.

The better idea would be to move to the Manual clone. Then it should
be easier to avoid this site title renaming problem *and* have a Search
box in the online released Manual.


>> If there is a new version of the file to download shouldn't we fix that too?
>
> I would hope that we can avoid going through a "release process" for a
> new version of the manual.
> Once you say "we'll just fix this little bit", then surely it makes
> sense to also fix "that little bit", and perhaps "that other little
> bit"...
>
> >From a support point of view, it is much 'cleaner' if all versions of
> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
> favour of 'only' repacking the manual, assuming that the manual in the
> EXE / DMG bundles are the same as the current ZIP'd manual.

+1.

>From James's description, the EXE/DMG contents are the same
as that of the ZIP, if we don't retitle the pages to "Audacity Manual".


> If the manual in the EXE / DMG are different to the current ZIP'd
> version, then I think we should package the EXE / DMG version as the
> new ZIP.
>
>>
>>>
>>>> What do we call the new package?
>>>> How about: "audacity-manual-2.1.3-1.zip"
>
> Assuming no changes to the content of the manual, I'm +1 for naming
> it: "audacity-manual-2.1.3-1.zip"

Out of interest, what would the name be if we did change the
content?

"-1" is ambiguous as to whether it is a just a repacking or a contents
change. To be unambiguous it could be e.g.

"audacity-manual-2.1.3-repacked.zip".


>>>>
>>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>>> If there is no disagreement about the need for it to be done, then
>>>> there is no decision to make other than how we go about fixing it.
>>> Just repackage it correctly with a new file name, as far as I am
>>> concerned.
>>>
>>>
>>> Gale
>>
>> We could fix/clarify the instructions at
>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>> and that would work just as well as a fix.
>
> Not as good a fix, because there's a million copies of the manual in the wild.

+1


>> I would presume we will shorten the install path for 2.2.0 help and
>> clarify those instructions for 2.2.0 to say where the help files should
>> end up.
>
> +1

Please make a specific proposal. We don't want A.N.Other extraction
utility spewing help files into the root of the app.


>
>>
>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
>> users who just fetch and unzip it have some instructions on how to make
>> Audacity find it.
>
> +1
> or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).

+1.  So does that instructions file need to be committed to the "help" folder
in Git?


>> I took my RM-is-God hat off after 2.1.3 release was announced, so you
>> shouldn't be waiting on me for approval.

James. you or someone who was helping you mispackaged the
Manual.

We are all human (and no-one in QA checked, given this has never
gone wrong before), but should it not be you or your helper who
fixes it?

I say we should repackage it, contents and page titles unchanged.


Gale

>> I'd imagine most users who
>> download the manual separately are accessing it directly rather than
>> from within Audacity
>> - and also that the vast majority of linux users use the manual on line.
>
> Looks to me like we need to do more to encourage users to use the manual ;-)
>
> As a regular user of open source software, our manual really is a huge
> and fantastic selling point for Audacity. History is littered with
> software that died through lack of good documentation. We should make
> much of it.
>
> Steve
>
>>
>> --James.
>>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Cliff Scott

> On May 10, 2017, at 2:54 PM, Gale Andrews <[hidden email]> wrote:
>
> On 10 May 2017 at 10:25, Steve the Fiddle <[hidden email]> wrote:
>> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>>>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>>>> James, it's broken for all users who intend to locate the
>>>>>> standalone zipped Manual from within Audacity.
>>>>>>
>>>>>> It would be good if a script could automate what is required,
>>>>>> but the "zipping" part of
>>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>>>> was not followed as it should have been (it's a clear part
>>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>>>> I think we can make the instruction clearer.
>>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>>>> before zipping it (with "Archive Manager").
>>>> Surely all a developer on any platform needs to know is the
>>>> structure that is wanted?
>>> I think the instructions on installing the manual (what paths to end up
>>> with after unzipping) and building the manual (the zipping part) both
>>> could be improved.  My install of RC3 (from innosetup) has the manual in
>>> the correct position with the correct name, (i.e. not development manual).
>>>
>>> Why do we have a ./help/manual/ in the path and not just ./help or just
>>> ./manual?  It seems an extra level that serves no purpose and just makes
>>> manual installation harder.
>>
>> I agree, the path to the manual is overly complex. I suspect that it
>> came about due to differences in archive extraction apps, with some
>> extracting the archive contents directly into the specified location,
>> and others extracting into a folder in the specified direction.
>
> Those differences seem to me to be compelling reason not to
> "improve" the developer instructions on building the Manual by
> giving per app instructions. .
>
> The developer can choose his app on his particular OS to package
> the zip, knowing that he has to produce a ZIP that:
>
>   "should produce a "help" folder with the "manual" folder inside that".
>
> All you need to do (for example) is to right-click the ZIP file you
> packaged > 7-Zip > Open Archive and check you are looking at the
> "help" folder.
>
>
>> what we want to avoid is spewing a mass of files into a location where
>> other (non-manual) files exist.
>>
>> My guess is that index.html and quick_help.html are outside of the
>> main "manual" folder so that the can be found easily by anyone wanting
>> to access the manual directly (rather than from Audacity).
>
>>>>>> If the corrected ZIP file needs to be renamed then
>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>>>
>>>>>> would have to change its link (that's the online copy of the
>>>>>> released Manual).  However it's a packaging change only, not
>>>>>> a change of content.
>>>>> The 'packaging' (the zipping process) is certainly wrong.
>>>>> Are the contents correct? I notice that the index page says:
>>>>>
>>>>> "Audacity Manual Contents
>>>>>> From Audacity Development Manual"
>>>> As I said before, that happens because the released Manual
>>>> is dumped from the development Manual. When users visit
>>>> the development Manual, we want the site title to say
>>>> "Audacity Development Manual" so they can distinguish it
>>>> from the online released Manual.
>>>>
>>>> So when we dump, we change the alphamanual site title
>>>> to "Audacity Manual" and while we wait to see if the RC will
>>>> pass, we change it back to "Audacity Development Manual" .
>>>> When we have a protracted release with many RCs, it's
>>>> easy to forget to change the alphamanual site title each time
>>>> the Manual is dumped.
>>>>
>>>> The contents are correct apart from that.
>>> I actually did that change to the html after the manual was pulled.
>
> How did you do that?  I know no way to do that, once the files are
> dumped, except text replace in all the files.
>
> I assumed we were trying to avoid "content changes". If someone
> downloaded the ZIP already, deleted it by accident then redownloads
> it with the page titles changed to "Audacity Manual", might that not
> be confusing? Is it the same Manual they had before?
>
>
>> So does the in-app Windows EXE / Mac DMG manual say "From the
>> Development Manual"?
>
> On Windows the 2.1.3 EXE installer produces page titles that say
> "Audacity Development Manual". I am 99% certain that Mac is the
> same, from memory.

FYI, if you're referring to the Manual that in included in the installer and installed subsequently installed to the local HD, my Mac 2.1.3 installation shows "Audacity 2.1.3 Manual" as it should.

Cliff

>
>
>>> We
>>> could incorporate it in the script that fetches the manual.
>>>
>>>> I really hope Buanzo will succeed with the Manual clone
>>>> because I assume that will solve this site title problem. :=)
>>>>
>>>>
>>>>> I've not seen the Windows version, but if that's the same, then I
>>>>> think we need to stick with that even though it looks a bit weird.
>>>> Yes.
>>> Why not fix it?
>
> ROI could be another reason.
>
> The better idea would be to move to the Manual clone. Then it should
> be easier to avoid this site title renaming problem *and* have a Search
> box in the online released Manual.
>
>
>>> If there is a new version of the file to download shouldn't we fix that too?
>>
>> I would hope that we can avoid going through a "release process" for a
>> new version of the manual.
>> Once you say "we'll just fix this little bit", then surely it makes
>> sense to also fix "that little bit", and perhaps "that other little
>> bit"...
>>
>>> From a support point of view, it is much 'cleaner' if all versions of
>> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
>> favour of 'only' repacking the manual, assuming that the manual in the
>> EXE / DMG bundles are the same as the current ZIP'd manual.
>
> +1.
>
>> From James's description, the EXE/DMG contents are the same
> as that of the ZIP, if we don't retitle the pages to "Audacity Manual".
>
>
>> If the manual in the EXE / DMG are different to the current ZIP'd
>> version, then I think we should package the EXE / DMG version as the
>> new ZIP.
>>
>>>
>>>>
>>>>> What do we call the new package?
>>>>> How about: "audacity-manual-2.1.3-1.zip"
>>
>> Assuming no changes to the content of the manual, I'm +1 for naming
>> it: "audacity-manual-2.1.3-1.zip"
>
> Out of interest, what would the name be if we did change the
> content?
>
> "-1" is ambiguous as to whether it is a just a repacking or a contents
> change. To be unambiguous it could be e.g.
>
> "audacity-manual-2.1.3-repacked.zip".
>
>
>>>>>
>>>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>>>> If there is no disagreement about the need for it to be done, then
>>>>> there is no decision to make other than how we go about fixing it.
>>>> Just repackage it correctly with a new file name, as far as I am
>>>> concerned.
>>>>
>>>>
>>>> Gale
>>>
>>> We could fix/clarify the instructions at
>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>> and that would work just as well as a fix.
>>
>> Not as good a fix, because there's a million copies of the manual in the wild.
>
> +1
>
>
>>> I would presume we will shorten the install path for 2.2.0 help and
>>> clarify those instructions for 2.2.0 to say where the help files should
>>> end up.
>>
>> +1
>
> Please make a specific proposal. We don't want A.N.Other extraction
> utility spewing help files into the root of the app.
>
>
>>
>>>
>>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
>>> users who just fetch and unzip it have some instructions on how to make
>>> Audacity find it.
>>
>> +1
>> or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).
>
> +1.  So does that instructions file need to be committed to the "help" folder
> in Git?
>
>
>>> I took my RM-is-God hat off after 2.1.3 release was announced, so you
>>> shouldn't be waiting on me for approval.
>
> James. you or someone who was helping you mispackaged the
> Manual.
>
> We are all human (and no-one in QA checked, given this has never
> gone wrong before), but should it not be you or your helper who
> fixes it?
>
> I say we should repackage it, contents and page titles unchanged.
>
>
> Gale
>
>>> I'd imagine most users who
>>> download the manual separately are accessing it directly rather than
>>> from within Audacity
>>> - and also that the vast majority of linux users use the manual on line.
>>
>> Looks to me like we need to do more to encourage users to use the manual ;-)
>>
>> As a regular user of open source software, our manual really is a huge
>> and fantastic selling point for Audacity. History is littered with
>> software that died through lack of good documentation. We should make
>> much of it.
>>
>> Steve
>>
>>>
>>> --James.
>>>
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Gale
Administrator
Hi Cliff,

Thanks, but no we are talking about the page title. If your browser
does not show page titles (many don't these days at default
settings), you can examine the source code of the file to confirm.



Gale


On 10 May 2017 at 22:36, Cliff Scott <[hidden email]> wrote:

>
>> On May 10, 2017, at 2:54 PM, Gale Andrews <[hidden email]> wrote:
>>
>> On 10 May 2017 at 10:25, Steve the Fiddle <[hidden email]> wrote:
>>> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>>>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>>>>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>>>>> James, it's broken for all users who intend to locate the
>>>>>>> standalone zipped Manual from within Audacity.
>>>>>>>
>>>>>>> It would be good if a script could automate what is required,
>>>>>>> but the "zipping" part of
>>>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>>>>> was not followed as it should have been (it's a clear part
>>>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>>>>> I think we can make the instruction clearer.
>>>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>>>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>>>>> before zipping it (with "Archive Manager").
>>>>> Surely all a developer on any platform needs to know is the
>>>>> structure that is wanted?
>>>> I think the instructions on installing the manual (what paths to end up
>>>> with after unzipping) and building the manual (the zipping part) both
>>>> could be improved.  My install of RC3 (from innosetup) has the manual in
>>>> the correct position with the correct name, (i.e. not development manual).
>>>>
>>>> Why do we have a ./help/manual/ in the path and not just ./help or just
>>>> ./manual?  It seems an extra level that serves no purpose and just makes
>>>> manual installation harder.
>>>
>>> I agree, the path to the manual is overly complex. I suspect that it
>>> came about due to differences in archive extraction apps, with some
>>> extracting the archive contents directly into the specified location,
>>> and others extracting into a folder in the specified direction.
>>
>> Those differences seem to me to be compelling reason not to
>> "improve" the developer instructions on building the Manual by
>> giving per app instructions. .
>>
>> The developer can choose his app on his particular OS to package
>> the zip, knowing that he has to produce a ZIP that:
>>
>>   "should produce a "help" folder with the "manual" folder inside that".
>>
>> All you need to do (for example) is to right-click the ZIP file you
>> packaged > 7-Zip > Open Archive and check you are looking at the
>> "help" folder.
>>
>>
>>> what we want to avoid is spewing a mass of files into a location where
>>> other (non-manual) files exist.
>>>
>>> My guess is that index.html and quick_help.html are outside of the
>>> main "manual" folder so that the can be found easily by anyone wanting
>>> to access the manual directly (rather than from Audacity).
>>
>>>>>>> If the corrected ZIP file needs to be renamed then
>>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>>>>
>>>>>>> would have to change its link (that's the online copy of the
>>>>>>> released Manual).  However it's a packaging change only, not
>>>>>>> a change of content.
>>>>>> The 'packaging' (the zipping process) is certainly wrong.
>>>>>> Are the contents correct? I notice that the index page says:
>>>>>>
>>>>>> "Audacity Manual Contents
>>>>>>> From Audacity Development Manual"
>>>>> As I said before, that happens because the released Manual
>>>>> is dumped from the development Manual. When users visit
>>>>> the development Manual, we want the site title to say
>>>>> "Audacity Development Manual" so they can distinguish it
>>>>> from the online released Manual.
>>>>>
>>>>> So when we dump, we change the alphamanual site title
>>>>> to "Audacity Manual" and while we wait to see if the RC will
>>>>> pass, we change it back to "Audacity Development Manual" .
>>>>> When we have a protracted release with many RCs, it's
>>>>> easy to forget to change the alphamanual site title each time
>>>>> the Manual is dumped.
>>>>>
>>>>> The contents are correct apart from that.
>>>> I actually did that change to the html after the manual was pulled.
>>
>> How did you do that?  I know no way to do that, once the files are
>> dumped, except text replace in all the files.
>>
>> I assumed we were trying to avoid "content changes". If someone
>> downloaded the ZIP already, deleted it by accident then redownloads
>> it with the page titles changed to "Audacity Manual", might that not
>> be confusing? Is it the same Manual they had before?
>>
>>
>>> So does the in-app Windows EXE / Mac DMG manual say "From the
>>> Development Manual"?
>>
>> On Windows the 2.1.3 EXE installer produces page titles that say
>> "Audacity Development Manual". I am 99% certain that Mac is the
>> same, from memory.
>
> FYI, if you're referring to the Manual that in included in the installer and installed subsequently installed to the local HD, my Mac 2.1.3 installation shows "Audacity 2.1.3 Manual" as it should.
>
> Cliff
>
>>
>>
>>>> We
>>>> could incorporate it in the script that fetches the manual.
>>>>
>>>>> I really hope Buanzo will succeed with the Manual clone
>>>>> because I assume that will solve this site title problem. :=)
>>>>>
>>>>>
>>>>>> I've not seen the Windows version, but if that's the same, then I
>>>>>> think we need to stick with that even though it looks a bit weird.
>>>>> Yes.
>>>> Why not fix it?
>>
>> ROI could be another reason.
>>
>> The better idea would be to move to the Manual clone. Then it should
>> be easier to avoid this site title renaming problem *and* have a Search
>> box in the online released Manual.
>>
>>
>>>> If there is a new version of the file to download shouldn't we fix that too?
>>>
>>> I would hope that we can avoid going through a "release process" for a
>>> new version of the manual.
>>> Once you say "we'll just fix this little bit", then surely it makes
>>> sense to also fix "that little bit", and perhaps "that other little
>>> bit"...
>>>
>>>> From a support point of view, it is much 'cleaner' if all versions of
>>> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
>>> favour of 'only' repacking the manual, assuming that the manual in the
>>> EXE / DMG bundles are the same as the current ZIP'd manual.
>>
>> +1.
>>
>>> From James's description, the EXE/DMG contents are the same
>> as that of the ZIP, if we don't retitle the pages to "Audacity Manual".
>>
>>
>>> If the manual in the EXE / DMG are different to the current ZIP'd
>>> version, then I think we should package the EXE / DMG version as the
>>> new ZIP.
>>>
>>>>
>>>>>
>>>>>> What do we call the new package?
>>>>>> How about: "audacity-manual-2.1.3-1.zip"
>>>
>>> Assuming no changes to the content of the manual, I'm +1 for naming
>>> it: "audacity-manual-2.1.3-1.zip"
>>
>> Out of interest, what would the name be if we did change the
>> content?
>>
>> "-1" is ambiguous as to whether it is a just a repacking or a contents
>> change. To be unambiguous it could be e.g.
>>
>> "audacity-manual-2.1.3-repacked.zip".
>>
>>
>>>>>>
>>>>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>>>>> If there is no disagreement about the need for it to be done, then
>>>>>> there is no decision to make other than how we go about fixing it.
>>>>> Just repackage it correctly with a new file name, as far as I am
>>>>> concerned.
>>>>>
>>>>>
>>>>> Gale
>>>>
>>>> We could fix/clarify the instructions at
>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>>> and that would work just as well as a fix.
>>>
>>> Not as good a fix, because there's a million copies of the manual in the wild.
>>
>> +1
>>
>>
>>>> I would presume we will shorten the install path for 2.2.0 help and
>>>> clarify those instructions for 2.2.0 to say where the help files should
>>>> end up.
>>>
>>> +1
>>
>> Please make a specific proposal. We don't want A.N.Other extraction
>> utility spewing help files into the root of the app.
>>
>>
>>>
>>>>
>>>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
>>>> users who just fetch and unzip it have some instructions on how to make
>>>> Audacity find it.
>>>
>>> +1
>>> or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).
>>
>> +1.  So does that instructions file need to be committed to the "help" folder
>> in Git?
>>
>>
>>>> I took my RM-is-God hat off after 2.1.3 release was announced, so you
>>>> shouldn't be waiting on me for approval.
>>
>> James. you or someone who was helping you mispackaged the
>> Manual.
>>
>> We are all human (and no-one in QA checked, given this has never
>> gone wrong before), but should it not be you or your helper who
>> fixes it?
>>
>> I say we should repackage it, contents and page titles unchanged.
>>
>>
>> Gale
>>
>>>> I'd imagine most users who
>>>> download the manual separately are accessing it directly rather than
>>>> from within Audacity
>>>> - and also that the vast majority of linux users use the manual on line.
>>>
>>> Looks to me like we need to do more to encourage users to use the manual ;-)
>>>
>>> As a regular user of open source software, our manual really is a huge
>>> and fantastic selling point for Audacity. History is littered with
>>> software that died through lack of good documentation. We should make
>>> much of it.
>>>
>>> Steve
>>>
>>>>
>>>> --James.
>>>>
>>>
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> [hidden email]
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Cliff Scott
Ok. I see what you are referring to. Yes it is as you expected, i.e.Audacity Development Manual.

Cliff

> On May 10, 2017, at 8:00 PM, Gale Andrews <[hidden email]> wrote:
>
> Hi Cliff,
>
> Thanks, but no we are talking about the page title. If your browser
> does not show page titles (many don't these days at default
> settings), you can examine the source code of the file to confirm.
>
>
>
> Gale
>
>
> On 10 May 2017 at 22:36, Cliff Scott <[hidden email]> wrote:
>>
>>> On May 10, 2017, at 2:54 PM, Gale Andrews <[hidden email]> wrote:
>>>
>>> On 10 May 2017 at 10:25, Steve the Fiddle <[hidden email]> wrote:
>>>> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>>>>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>>>>>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>>>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>>>>>> James, it's broken for all users who intend to locate the
>>>>>>>> standalone zipped Manual from within Audacity.
>>>>>>>>
>>>>>>>> It would be good if a script could automate what is required,
>>>>>>>> but the "zipping" part of
>>>>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>>>>>> was not followed as it should have been (it's a clear part
>>>>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>>>>>> I think we can make the instruction clearer.
>>>>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>>>>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>>>>>> before zipping it (with "Archive Manager").
>>>>>> Surely all a developer on any platform needs to know is the
>>>>>> structure that is wanted?
>>>>> I think the instructions on installing the manual (what paths to end up
>>>>> with after unzipping) and building the manual (the zipping part) both
>>>>> could be improved.  My install of RC3 (from innosetup) has the manual in
>>>>> the correct position with the correct name, (i.e. not development manual).
>>>>>
>>>>> Why do we have a ./help/manual/ in the path and not just ./help or just
>>>>> ./manual?  It seems an extra level that serves no purpose and just makes
>>>>> manual installation harder.
>>>>
>>>> I agree, the path to the manual is overly complex. I suspect that it
>>>> came about due to differences in archive extraction apps, with some
>>>> extracting the archive contents directly into the specified location,
>>>> and others extracting into a folder in the specified direction.
>>>
>>> Those differences seem to me to be compelling reason not to
>>> "improve" the developer instructions on building the Manual by
>>> giving per app instructions. .
>>>
>>> The developer can choose his app on his particular OS to package
>>> the zip, knowing that he has to produce a ZIP that:
>>>
>>>  "should produce a "help" folder with the "manual" folder inside that".
>>>
>>> All you need to do (for example) is to right-click the ZIP file you
>>> packaged > 7-Zip > Open Archive and check you are looking at the
>>> "help" folder.
>>>
>>>
>>>> what we want to avoid is spewing a mass of files into a location where
>>>> other (non-manual) files exist.
>>>>
>>>> My guess is that index.html and quick_help.html are outside of the
>>>> main "manual" folder so that the can be found easily by anyone wanting
>>>> to access the manual directly (rather than from Audacity).
>>>
>>>>>>>> If the corrected ZIP file needs to be renamed then
>>>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>>>>>
>>>>>>>> would have to change its link (that's the online copy of the
>>>>>>>> released Manual).  However it's a packaging change only, not
>>>>>>>> a change of content.
>>>>>>> The 'packaging' (the zipping process) is certainly wrong.
>>>>>>> Are the contents correct? I notice that the index page says:
>>>>>>>
>>>>>>> "Audacity Manual Contents
>>>>>>>> From Audacity Development Manual"
>>>>>> As I said before, that happens because the released Manual
>>>>>> is dumped from the development Manual. When users visit
>>>>>> the development Manual, we want the site title to say
>>>>>> "Audacity Development Manual" so they can distinguish it
>>>>>> from the online released Manual.
>>>>>>
>>>>>> So when we dump, we change the alphamanual site title
>>>>>> to "Audacity Manual" and while we wait to see if the RC will
>>>>>> pass, we change it back to "Audacity Development Manual" .
>>>>>> When we have a protracted release with many RCs, it's
>>>>>> easy to forget to change the alphamanual site title each time
>>>>>> the Manual is dumped.
>>>>>>
>>>>>> The contents are correct apart from that.
>>>>> I actually did that change to the html after the manual was pulled.
>>>
>>> How did you do that?  I know no way to do that, once the files are
>>> dumped, except text replace in all the files.
>>>
>>> I assumed we were trying to avoid "content changes". If someone
>>> downloaded the ZIP already, deleted it by accident then redownloads
>>> it with the page titles changed to "Audacity Manual", might that not
>>> be confusing? Is it the same Manual they had before?
>>>
>>>
>>>> So does the in-app Windows EXE / Mac DMG manual say "From the
>>>> Development Manual"?
>>>
>>> On Windows the 2.1.3 EXE installer produces page titles that say
>>> "Audacity Development Manual". I am 99% certain that Mac is the
>>> same, from memory.
>>
>> FYI, if you're referring to the Manual that in included in the installer and installed subsequently installed to the local HD, my Mac 2.1.3 installation shows "Audacity 2.1.3 Manual" as it should.
>>
>> Cliff
>>
>>>
>>>
>>>>> We
>>>>> could incorporate it in the script that fetches the manual.
>>>>>
>>>>>> I really hope Buanzo will succeed with the Manual clone
>>>>>> because I assume that will solve this site title problem. :=)
>>>>>>
>>>>>>
>>>>>>> I've not seen the Windows version, but if that's the same, then I
>>>>>>> think we need to stick with that even though it looks a bit weird.
>>>>>> Yes.
>>>>> Why not fix it?
>>>
>>> ROI could be another reason.
>>>
>>> The better idea would be to move to the Manual clone. Then it should
>>> be easier to avoid this site title renaming problem *and* have a Search
>>> box in the online released Manual.
>>>
>>>
>>>>> If there is a new version of the file to download shouldn't we fix that too?
>>>>
>>>> I would hope that we can avoid going through a "release process" for a
>>>> new version of the manual.
>>>> Once you say "we'll just fix this little bit", then surely it makes
>>>> sense to also fix "that little bit", and perhaps "that other little
>>>> bit"...
>>>>
>>>>> From a support point of view, it is much 'cleaner' if all versions of
>>>> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
>>>> favour of 'only' repacking the manual, assuming that the manual in the
>>>> EXE / DMG bundles are the same as the current ZIP'd manual.
>>>
>>> +1.
>>>
>>>> From James's description, the EXE/DMG contents are the same
>>> as that of the ZIP, if we don't retitle the pages to "Audacity Manual".
>>>
>>>
>>>> If the manual in the EXE / DMG are different to the current ZIP'd
>>>> version, then I think we should package the EXE / DMG version as the
>>>> new ZIP.
>>>>
>>>>>
>>>>>>
>>>>>>> What do we call the new package?
>>>>>>> How about: "audacity-manual-2.1.3-1.zip"
>>>>
>>>> Assuming no changes to the content of the manual, I'm +1 for naming
>>>> it: "audacity-manual-2.1.3-1.zip"
>>>
>>> Out of interest, what would the name be if we did change the
>>> content?
>>>
>>> "-1" is ambiguous as to whether it is a just a repacking or a contents
>>> change. To be unambiguous it could be e.g.
>>>
>>> "audacity-manual-2.1.3-repacked.zip".
>>>
>>>
>>>>>>>
>>>>>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>>>>>> If there is no disagreement about the need for it to be done, then
>>>>>>> there is no decision to make other than how we go about fixing it.
>>>>>> Just repackage it correctly with a new file name, as far as I am
>>>>>> concerned.
>>>>>>
>>>>>>
>>>>>> Gale
>>>>>
>>>>> We could fix/clarify the instructions at
>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>>>> and that would work just as well as a fix.
>>>>
>>>> Not as good a fix, because there's a million copies of the manual in the wild.
>>>
>>> +1
>>>
>>>
>>>>> I would presume we will shorten the install path for 2.2.0 help and
>>>>> clarify those instructions for 2.2.0 to say where the help files should
>>>>> end up.
>>>>
>>>> +1
>>>
>>> Please make a specific proposal. We don't want A.N.Other extraction
>>> utility spewing help files into the root of the app.
>>>
>>>
>>>>
>>>>>
>>>>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
>>>>> users who just fetch and unzip it have some instructions on how to make
>>>>> Audacity find it.
>>>>
>>>> +1
>>>> or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).
>>>
>>> +1.  So does that instructions file need to be committed to the "help" folder
>>> in Git?
>>>
>>>
>>>>> I took my RM-is-God hat off after 2.1.3 release was announced, so you
>>>>> shouldn't be waiting on me for approval.
>>>
>>> James. you or someone who was helping you mispackaged the
>>> Manual.
>>>
>>> We are all human (and no-one in QA checked, given this has never
>>> gone wrong before), but should it not be you or your helper who
>>> fixes it?
>>>
>>> I say we should repackage it, contents and page titles unchanged.
>>>
>>>
>>> Gale
>>>
>>>>> I'd imagine most users who
>>>>> download the manual separately are accessing it directly rather than
>>>>> from within Audacity
>>>>> - and also that the vast majority of linux users use the manual on line.
>>>>
>>>> Looks to me like we need to do more to encourage users to use the manual ;-)
>>>>
>>>> As a regular user of open source software, our manual really is a huge
>>>> and fantastic selling point for Audacity. History is littered with
>>>> software that died through lack of good documentation. We should make
>>>> much of it.
>>>>
>>>> Steve
>>>>
>>>>>
>>>>> --James.
>>>>>
>>>>
>>>> ------------------------------------------------------------------------------
>>>> Check out the vibrant tech community on one of the world's most
>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>> _______________________________________________
>>>> Audacity-quality mailing list
>>>> [hidden email]
>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> [hidden email]
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Stevethefiddle
On 11 May 2017 at 02:39, Cliff Scott <[hidden email]> wrote:

> Ok. I see what you are referring to. Yes it is as you expected, i.e.Audacity Development Manual.
>
> Cliff
>
>> On May 10, 2017, at 8:00 PM, Gale Andrews <[hidden email]> wrote:
>>
>> Hi Cliff,
>>
>> Thanks, but no we are talking about the page title. If your browser
>> does not show page titles (many don't these days at default
>> settings), you can examine the source code of the file to confirm.

Also, if the CSS theme is off, then "From Audacity Development Manual"
is displayed as a sub-heading.
I discovered that accidentally while moving folders to make Help work
in Audacity (I had the "m" folder in the wrong location).
Do screen readers read it?

Steve

>>
>>
>>
>> Gale
>>
>>
>> On 10 May 2017 at 22:36, Cliff Scott <[hidden email]> wrote:
>>>
>>>> On May 10, 2017, at 2:54 PM, Gale Andrews <[hidden email]> wrote:
>>>>
>>>> On 10 May 2017 at 10:25, Steve the Fiddle <[hidden email]> wrote:
>>>>> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>>>>>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>>>>>>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>>>>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>>>>>>> James, it's broken for all users who intend to locate the
>>>>>>>>> standalone zipped Manual from within Audacity.
>>>>>>>>>
>>>>>>>>> It would be good if a script could automate what is required,
>>>>>>>>> but the "zipping" part of
>>>>>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>>>>>>> was not followed as it should have been (it's a clear part
>>>>>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>>>>>>> I think we can make the instruction clearer.
>>>>>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>>>>>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>>>>>>> before zipping it (with "Archive Manager").
>>>>>>> Surely all a developer on any platform needs to know is the
>>>>>>> structure that is wanted?
>>>>>> I think the instructions on installing the manual (what paths to end up
>>>>>> with after unzipping) and building the manual (the zipping part) both
>>>>>> could be improved.  My install of RC3 (from innosetup) has the manual in
>>>>>> the correct position with the correct name, (i.e. not development manual).
>>>>>>
>>>>>> Why do we have a ./help/manual/ in the path and not just ./help or just
>>>>>> ./manual?  It seems an extra level that serves no purpose and just makes
>>>>>> manual installation harder.
>>>>>
>>>>> I agree, the path to the manual is overly complex. I suspect that it
>>>>> came about due to differences in archive extraction apps, with some
>>>>> extracting the archive contents directly into the specified location,
>>>>> and others extracting into a folder in the specified direction.
>>>>
>>>> Those differences seem to me to be compelling reason not to
>>>> "improve" the developer instructions on building the Manual by
>>>> giving per app instructions. .
>>>>
>>>> The developer can choose his app on his particular OS to package
>>>> the zip, knowing that he has to produce a ZIP that:
>>>>
>>>>  "should produce a "help" folder with the "manual" folder inside that".
>>>>
>>>> All you need to do (for example) is to right-click the ZIP file you
>>>> packaged > 7-Zip > Open Archive and check you are looking at the
>>>> "help" folder.
>>>>
>>>>
>>>>> what we want to avoid is spewing a mass of files into a location where
>>>>> other (non-manual) files exist.
>>>>>
>>>>> My guess is that index.html and quick_help.html are outside of the
>>>>> main "manual" folder so that the can be found easily by anyone wanting
>>>>> to access the manual directly (rather than from Audacity).
>>>>
>>>>>>>>> If the corrected ZIP file needs to be renamed then
>>>>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>>>>>>
>>>>>>>>> would have to change its link (that's the online copy of the
>>>>>>>>> released Manual).  However it's a packaging change only, not
>>>>>>>>> a change of content.
>>>>>>>> The 'packaging' (the zipping process) is certainly wrong.
>>>>>>>> Are the contents correct? I notice that the index page says:
>>>>>>>>
>>>>>>>> "Audacity Manual Contents
>>>>>>>>> From Audacity Development Manual"
>>>>>>> As I said before, that happens because the released Manual
>>>>>>> is dumped from the development Manual. When users visit
>>>>>>> the development Manual, we want the site title to say
>>>>>>> "Audacity Development Manual" so they can distinguish it
>>>>>>> from the online released Manual.
>>>>>>>
>>>>>>> So when we dump, we change the alphamanual site title
>>>>>>> to "Audacity Manual" and while we wait to see if the RC will
>>>>>>> pass, we change it back to "Audacity Development Manual" .
>>>>>>> When we have a protracted release with many RCs, it's
>>>>>>> easy to forget to change the alphamanual site title each time
>>>>>>> the Manual is dumped.
>>>>>>>
>>>>>>> The contents are correct apart from that.
>>>>>> I actually did that change to the html after the manual was pulled.
>>>>
>>>> How did you do that?  I know no way to do that, once the files are
>>>> dumped, except text replace in all the files.
>>>>
>>>> I assumed we were trying to avoid "content changes". If someone
>>>> downloaded the ZIP already, deleted it by accident then redownloads
>>>> it with the page titles changed to "Audacity Manual", might that not
>>>> be confusing? Is it the same Manual they had before?
>>>>
>>>>
>>>>> So does the in-app Windows EXE / Mac DMG manual say "From the
>>>>> Development Manual"?
>>>>
>>>> On Windows the 2.1.3 EXE installer produces page titles that say
>>>> "Audacity Development Manual". I am 99% certain that Mac is the
>>>> same, from memory.
>>>
>>> FYI, if you're referring to the Manual that in included in the installer and installed subsequently installed to the local HD, my Mac 2.1.3 installation shows "Audacity 2.1.3 Manual" as it should.
>>>
>>> Cliff
>>>
>>>>
>>>>
>>>>>> We
>>>>>> could incorporate it in the script that fetches the manual.
>>>>>>
>>>>>>> I really hope Buanzo will succeed with the Manual clone
>>>>>>> because I assume that will solve this site title problem. :=)
>>>>>>>
>>>>>>>
>>>>>>>> I've not seen the Windows version, but if that's the same, then I
>>>>>>>> think we need to stick with that even though it looks a bit weird.
>>>>>>> Yes.
>>>>>> Why not fix it?
>>>>
>>>> ROI could be another reason.
>>>>
>>>> The better idea would be to move to the Manual clone. Then it should
>>>> be easier to avoid this site title renaming problem *and* have a Search
>>>> box in the online released Manual.
>>>>
>>>>
>>>>>> If there is a new version of the file to download shouldn't we fix that too?
>>>>>
>>>>> I would hope that we can avoid going through a "release process" for a
>>>>> new version of the manual.
>>>>> Once you say "we'll just fix this little bit", then surely it makes
>>>>> sense to also fix "that little bit", and perhaps "that other little
>>>>> bit"...
>>>>>
>>>>>> From a support point of view, it is much 'cleaner' if all versions of
>>>>> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
>>>>> favour of 'only' repacking the manual, assuming that the manual in the
>>>>> EXE / DMG bundles are the same as the current ZIP'd manual.
>>>>
>>>> +1.
>>>>
>>>>> From James's description, the EXE/DMG contents are the same
>>>> as that of the ZIP, if we don't retitle the pages to "Audacity Manual".
>>>>
>>>>
>>>>> If the manual in the EXE / DMG are different to the current ZIP'd
>>>>> version, then I think we should package the EXE / DMG version as the
>>>>> new ZIP.
>>>>>
>>>>>>
>>>>>>>
>>>>>>>> What do we call the new package?
>>>>>>>> How about: "audacity-manual-2.1.3-1.zip"
>>>>>
>>>>> Assuming no changes to the content of the manual, I'm +1 for naming
>>>>> it: "audacity-manual-2.1.3-1.zip"
>>>>
>>>> Out of interest, what would the name be if we did change the
>>>> content?
>>>>
>>>> "-1" is ambiguous as to whether it is a just a repacking or a contents
>>>> change. To be unambiguous it could be e.g.
>>>>
>>>> "audacity-manual-2.1.3-repacked.zip".
>>>>
>>>>
>>>>>>>>
>>>>>>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>>>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>>>>>>> If there is no disagreement about the need for it to be done, then
>>>>>>>> there is no decision to make other than how we go about fixing it.
>>>>>>> Just repackage it correctly with a new file name, as far as I am
>>>>>>> concerned.
>>>>>>>
>>>>>>>
>>>>>>> Gale
>>>>>>
>>>>>> We could fix/clarify the instructions at
>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>>>>> and that would work just as well as a fix.
>>>>>
>>>>> Not as good a fix, because there's a million copies of the manual in the wild.
>>>>
>>>> +1
>>>>
>>>>
>>>>>> I would presume we will shorten the install path for 2.2.0 help and
>>>>>> clarify those instructions for 2.2.0 to say where the help files should
>>>>>> end up.
>>>>>
>>>>> +1
>>>>
>>>> Please make a specific proposal. We don't want A.N.Other extraction
>>>> utility spewing help files into the root of the app.
>>>>
>>>>
>>>>>
>>>>>>
>>>>>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
>>>>>> users who just fetch and unzip it have some instructions on how to make
>>>>>> Audacity find it.
>>>>>
>>>>> +1
>>>>> or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).
>>>>
>>>> +1.  So does that instructions file need to be committed to the "help" folder
>>>> in Git?
>>>>
>>>>
>>>>>> I took my RM-is-God hat off after 2.1.3 release was announced, so you
>>>>>> shouldn't be waiting on me for approval.
>>>>
>>>> James. you or someone who was helping you mispackaged the
>>>> Manual.
>>>>
>>>> We are all human (and no-one in QA checked, given this has never
>>>> gone wrong before), but should it not be you or your helper who
>>>> fixes it?
>>>>
>>>> I say we should repackage it, contents and page titles unchanged.
>>>>
>>>>
>>>> Gale
>>>>
>>>>>> I'd imagine most users who
>>>>>> download the manual separately are accessing it directly rather than
>>>>>> from within Audacity
>>>>>> - and also that the vast majority of linux users use the manual on line.
>>>>>
>>>>> Looks to me like we need to do more to encourage users to use the manual ;-)
>>>>>
>>>>> As a regular user of open source software, our manual really is a huge
>>>>> and fantastic selling point for Audacity. History is littered with
>>>>> software that died through lack of good documentation. We should make
>>>>> much of it.
>>>>>
>>>>> Steve
>>>>>
>>>>>>
>>>>>> --James.
>>>>>>
>>>>>
>>>>> ------------------------------------------------------------------------------
>>>>> Check out the vibrant tech community on one of the world's most
>>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>>> _______________________________________________
>>>>> Audacity-quality mailing list
>>>>> [hidden email]
>>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>>
>>>> ------------------------------------------------------------------------------
>>>> Check out the vibrant tech community on one of the world's most
>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>> _______________________________________________
>>>> Audacity-quality mailing list
>>>> [hidden email]
>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>
>>>
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> [hidden email]
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Stevethefiddle
In reply to this post by Gale
On 10 May 2017 at 20:54, Gale Andrews <[hidden email]> wrote:

> On 10 May 2017 at 10:25, Steve the Fiddle <[hidden email]> wrote:
>> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>>>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>>>> James, it's broken for all users who intend to locate the
>>>>>> standalone zipped Manual from within Audacity.
>>>>>>
>>>>>> It would be good if a script could automate what is required,
>>>>>> but the "zipping" part of
>>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>>>> was not followed as it should have been (it's a clear part
>>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>>>> I think we can make the instruction clearer.
>>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>>>> before zipping it (with "Archive Manager").
>>>> Surely all a developer on any platform needs to know is the
>>>> structure that is wanted?
>>> I think the instructions on installing the manual (what paths to end up
>>> with after unzipping) and building the manual (the zipping part) both
>>> could be improved.  My install of RC3 (from innosetup) has the manual in
>>> the correct position with the correct name, (i.e. not development manual).
>>>
>>> Why do we have a ./help/manual/ in the path and not just ./help or just
>>> ./manual?  It seems an extra level that serves no purpose and just makes
>>> manual installation harder.
>>
>> I agree, the path to the manual is overly complex. I suspect that it
>> came about due to differences in archive extraction apps, with some
>> extracting the archive contents directly into the specified location,
>> and others extracting into a folder in the specified direction.
>
> Those differences seem to me to be compelling reason not to
> "improve" the developer instructions on building the Manual by
> giving per app instructions. .
>
> The developer can choose his app on his particular OS to package
> the zip, knowing that he has to produce a ZIP that:
>
>    "should produce a "help" folder with the "manual" folder inside that".
>
> All you need to do (for example) is to right-click the ZIP file you
> packaged > 7-Zip > Open Archive and check you are looking at the
> "help" folder.
>
>
>> what we want to avoid is spewing a mass of files into a location where
>> other (non-manual) files exist.
>>
>> My guess is that index.html and quick_help.html are outside of the
>> main "manual" folder so that the can be found easily by anyone wanting
>> to access the manual directly (rather than from Audacity).
>
>>>>>> If the corrected ZIP file needs to be renamed then
>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>>>
>>>>>> would have to change its link (that's the online copy of the
>>>>>> released Manual).  However it's a packaging change only, not
>>>>>> a change of content.
>>>>> The 'packaging' (the zipping process) is certainly wrong.
>>>>> Are the contents correct? I notice that the index page says:
>>>>>
>>>>> "Audacity Manual Contents
>>>>> >From Audacity Development Manual"
>>>> As I said before, that happens because the released Manual
>>>> is dumped from the development Manual. When users visit
>>>> the development Manual, we want the site title to say
>>>> "Audacity Development Manual" so they can distinguish it
>>>> from the online released Manual.
>>>>
>>>> So when we dump, we change the alphamanual site title
>>>> to "Audacity Manual" and while we wait to see if the RC will
>>>> pass, we change it back to "Audacity Development Manual" .
>>>> When we have a protracted release with many RCs, it's
>>>> easy to forget to change the alphamanual site title each time
>>>> the Manual is dumped.
>>>>
>>>> The contents are correct apart from that.
>>> I actually did that change to the html after the manual was pulled.
>
> How did you do that?  I know no way to do that, once the files are
> dumped, except text replace in all the files.
>
> I assumed we were trying to avoid "content changes". If someone
> downloaded the ZIP already, deleted it by accident then redownloads
> it with the page titles changed to "Audacity Manual", might that not
> be confusing? Is it the same Manual they had before?
>
>
>> So does the in-app Windows EXE / Mac DMG manual say "From the
>> Development Manual"?
>
> On Windows the 2.1.3 EXE installer produces page titles that say
> "Audacity Development Manual". I am 99% certain that Mac is the
> same, from memory.
>
>
>>> We
>>> could incorporate it in the script that fetches the manual.
>>>
>>>> I really hope Buanzo will succeed with the Manual clone
>>>> because I assume that will solve this site title problem. :=)
>>>>
>>>>
>>>>> I've not seen the Windows version, but if that's the same, then I
>>>>> think we need to stick with that even though it looks a bit weird.
>>>> Yes.
>>> Why not fix it?
>
> ROI could be another reason.
>
> The better idea would be to move to the Manual clone. Then it should
> be easier to avoid this site title renaming problem *and* have a Search
> box in the online released Manual.
>
>
>>> If there is a new version of the file to download shouldn't we fix that too?
>>
>> I would hope that we can avoid going through a "release process" for a
>> new version of the manual.
>> Once you say "we'll just fix this little bit", then surely it makes
>> sense to also fix "that little bit", and perhaps "that other little
>> bit"...
>>
>> >From a support point of view, it is much 'cleaner' if all versions of
>> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
>> favour of 'only' repacking the manual, assuming that the manual in the
>> EXE / DMG bundles are the same as the current ZIP'd manual.
>
> +1.
>
> >From James's description, the EXE/DMG contents are the same
> as that of the ZIP, if we don't retitle the pages to "Audacity Manual".
>
>
>> If the manual in the EXE / DMG are different to the current ZIP'd
>> version, then I think we should package the EXE / DMG version as the
>> new ZIP.
>>
>>>
>>>>
>>>>> What do we call the new package?
>>>>> How about: "audacity-manual-2.1.3-1.zip"
>>
>> Assuming no changes to the content of the manual, I'm +1 for naming
>> it: "audacity-manual-2.1.3-1.zip"
>
> Out of interest, what would the name be if we did change the
> content?
>
> "-1" is ambiguous as to whether it is a just a repacking or a contents
> change. To be unambiguous it could be e.g.
>
> "audacity-manual-2.1.3-repacked.zip".
>
>
>>>>>
>>>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>>>> If there is no disagreement about the need for it to be done, then
>>>>> there is no decision to make other than how we go about fixing it.
>>>> Just repackage it correctly with a new file name, as far as I am
>>>> concerned.
>>>>
>>>>
>>>> Gale
>>>
>>> We could fix/clarify the instructions at
>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>> and that would work just as well as a fix.
>>
>> Not as good a fix, because there's a million copies of the manual in the wild.
>
> +1
>
>
>>> I would presume we will shorten the install path for 2.2.0 help and
>>> clarify those instructions for 2.2.0 to say where the help files should
>>> end up.
>>
>> +1
>
> Please make a specific proposal. We don't want A.N.Other extraction
> utility spewing help files into the root of the app.

Something like this:

------------
* help (top level folder)

** index.html
** quick_help.html
** README.TXT (or "INSTALL.TXT" or similar)

** manual (second level folder)
*** images (third level folder)
*** js (third level folder)
*** css (third level folder)
*** skins (third level folder)
*** <pages> html files
------------

So top level is just one folder: "help"
which contains 3 files and one folder: "manual".

The "manual" folder contains everything else.
Third level folders and below will be largely determined by the technology.

Steve

>
>
>>
>>>
>>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
>>> users who just fetch and unzip it have some instructions on how to make
>>> Audacity find it.
>>
>> +1
>> or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).
>
> +1.  So does that instructions file need to be committed to the "help" folder
> in Git?
>
>
>>> I took my RM-is-God hat off after 2.1.3 release was announced, so you
>>> shouldn't be waiting on me for approval.
>
> James. you or someone who was helping you mispackaged the
> Manual.
>
> We are all human (and no-one in QA checked, given this has never
> gone wrong before), but should it not be you or your helper who
> fixes it?
>
> I say we should repackage it, contents and page titles unchanged.
>
>
> Gale
>
>>> I'd imagine most users who
>>> download the manual separately are accessing it directly rather than
>>> from within Audacity
>>> - and also that the vast majority of linux users use the manual on line.
>>
>> Looks to me like we need to do more to encourage users to use the manual ;-)
>>
>> As a regular user of open source software, our manual really is a huge
>> and fantastic selling point for Audacity. History is littered with
>> software that died through lack of good documentation. We should make
>> much of it.
>>
>> Steve
>>
>>>
>>> --James.
>>>
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

David Bailes-3
In reply to this post by Stevethefiddle
On Thu, May 11, 2017 at 10:03 AM, Steve the Fiddle <[hidden email]> wrote:
On 11 May 2017 at 02:39, Cliff Scott <[hidden email]> wrote:
> Ok. I see what you are referring to. Yes it is as you expected, i.e.Audacity Development Manual.
>
> Cliff
>
>> On May 10, 2017, at 8:00 PM, Gale Andrews <[hidden email]> wrote:
>>
>> Hi Cliff,
>>
>> Thanks, but no we are talking about the page title. If your browser
>> does not show page titles (many don't these days at default
>> settings), you can examine the source code of the file to confirm.

Also, if the CSS theme is off, then "From Audacity Development Manual"
is displayed as a sub-heading.
I discovered that accidentally while moving folders to make Help work
in Audacity (I had the "m" folder in the wrong location).
Do screen readers read it?

If text is set to display:none in the css, it's not read by screen readers,

David.
 

Steve

>>
>>
>>
>> Gale
>>
>>
>> On 10 May 2017 at 22:36, Cliff Scott <[hidden email]> wrote:
>>>
>>>> On May 10, 2017, at 2:54 PM, Gale Andrews <[hidden email]> wrote:
>>>>
>>>> On 10 May 2017 at 10:25, Steve the Fiddle <[hidden email]> wrote:
>>>>> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>>>>>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>>>>>>> On 10 May 2017 at 01:32, Steve the Fiddle <[hidden email]> wrote:
>>>>>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]> wrote:
>>>>>>>>> James, it's broken for all users who intend to locate the
>>>>>>>>> standalone zipped Manual from within Audacity.
>>>>>>>>>
>>>>>>>>> It would be good if a script could automate what is required,
>>>>>>>>> but the "zipping" part of
>>>>>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>>>>>>>>> was not followed as it should have been (it's a clear part
>>>>>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>>>>>>>> I think we can make the instruction clearer.
>>>>>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>>>>>>>> (downloaded with the wiki2htm.sh script) into an empty "help" folder
>>>>>>>> before zipping it (with "Archive Manager").
>>>>>>> Surely all a developer on any platform needs to know is the
>>>>>>> structure that is wanted?
>>>>>> I think the instructions on installing the manual (what paths to end up
>>>>>> with after unzipping) and building the manual (the zipping part) both
>>>>>> could be improved.  My install of RC3 (from innosetup) has the manual in
>>>>>> the correct position with the correct name, (i.e. not development manual).
>>>>>>
>>>>>> Why do we have a ./help/manual/ in the path and not just ./help or just
>>>>>> ./manual?  It seems an extra level that serves no purpose and just makes
>>>>>> manual installation harder.
>>>>>
>>>>> I agree, the path to the manual is overly complex. I suspect that it
>>>>> came about due to differences in archive extraction apps, with some
>>>>> extracting the archive contents directly into the specified location,
>>>>> and others extracting into a folder in the specified direction.
>>>>
>>>> Those differences seem to me to be compelling reason not to
>>>> "improve" the developer instructions on building the Manual by
>>>> giving per app instructions. .
>>>>
>>>> The developer can choose his app on his particular OS to package
>>>> the zip, knowing that he has to produce a ZIP that:
>>>>
>>>>  "should produce a "help" folder with the "manual" folder inside that".
>>>>
>>>> All you need to do (for example) is to right-click the ZIP file you
>>>> packaged > 7-Zip > Open Archive and check you are looking at the
>>>> "help" folder.
>>>>
>>>>
>>>>> what we want to avoid is spewing a mass of files into a location where
>>>>> other (non-manual) files exist.
>>>>>
>>>>> My guess is that index.html and quick_help.html are outside of the
>>>>> main "manual" folder so that the can be found easily by anyone wanting
>>>>> to access the manual directly (rather than from Audacity).
>>>>
>>>>>>>>> If the corrected ZIP file needs to be renamed then
>>>>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>>>>>>>>>
>>>>>>>>> would have to change its link (that's the online copy of the
>>>>>>>>> released Manual).  However it's a packaging change only, not
>>>>>>>>> a change of content.
>>>>>>>> The 'packaging' (the zipping process) is certainly wrong.
>>>>>>>> Are the contents correct? I notice that the index page says:
>>>>>>>>
>>>>>>>> "Audacity Manual Contents
>>>>>>>>> From Audacity Development Manual"
>>>>>>> As I said before, that happens because the released Manual
>>>>>>> is dumped from the development Manual. When users visit
>>>>>>> the development Manual, we want the site title to say
>>>>>>> "Audacity Development Manual" so they can distinguish it
>>>>>>> from the online released Manual.
>>>>>>>
>>>>>>> So when we dump, we change the alphamanual site title
>>>>>>> to "Audacity Manual" and while we wait to see if the RC will
>>>>>>> pass, we change it back to "Audacity Development Manual" .
>>>>>>> When we have a protracted release with many RCs, it's
>>>>>>> easy to forget to change the alphamanual site title each time
>>>>>>> the Manual is dumped.
>>>>>>>
>>>>>>> The contents are correct apart from that.
>>>>>> I actually did that change to the html after the manual was pulled.
>>>>
>>>> How did you do that?  I know no way to do that, once the files are
>>>> dumped, except text replace in all the files.
>>>>
>>>> I assumed we were trying to avoid "content changes". If someone
>>>> downloaded the ZIP already, deleted it by accident then redownloads
>>>> it with the page titles changed to "Audacity Manual", might that not
>>>> be confusing? Is it the same Manual they had before?
>>>>
>>>>
>>>>> So does the in-app Windows EXE / Mac DMG manual say "From the
>>>>> Development Manual"?
>>>>
>>>> On Windows the 2.1.3 EXE installer produces page titles that say
>>>> "Audacity Development Manual". I am 99% certain that Mac is the
>>>> same, from memory.
>>>
>>> FYI, if you're referring to the Manual that in included in the installer and installed subsequently installed to the local HD, my Mac 2.1.3 installation shows "Audacity 2.1.3 Manual" as it should.
>>>
>>> Cliff
>>>
>>>>
>>>>
>>>>>> We
>>>>>> could incorporate it in the script that fetches the manual.
>>>>>>
>>>>>>> I really hope Buanzo will succeed with the Manual clone
>>>>>>> because I assume that will solve this site title problem. :=)
>>>>>>>
>>>>>>>
>>>>>>>> I've not seen the Windows version, but if that's the same, then I
>>>>>>>> think we need to stick with that even though it looks a bit weird.
>>>>>>> Yes.
>>>>>> Why not fix it?
>>>>
>>>> ROI could be another reason.
>>>>
>>>> The better idea would be to move to the Manual clone. Then it should
>>>> be easier to avoid this site title renaming problem *and* have a Search
>>>> box in the online released Manual.
>>>>
>>>>
>>>>>> If there is a new version of the file to download shouldn't we fix that too?
>>>>>
>>>>> I would hope that we can avoid going through a "release process" for a
>>>>> new version of the manual.
>>>>> Once you say "we'll just fix this little bit", then surely it makes
>>>>> sense to also fix "that little bit", and perhaps "that other little
>>>>> bit"...
>>>>>
>>>>>> From a support point of view, it is much 'cleaner' if all versions of
>>>>> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
>>>>> favour of 'only' repacking the manual, assuming that the manual in the
>>>>> EXE / DMG bundles are the same as the current ZIP'd manual.
>>>>
>>>> +1.
>>>>
>>>>> From James's description, the EXE/DMG contents are the same
>>>> as that of the ZIP, if we don't retitle the pages to "Audacity Manual".
>>>>
>>>>
>>>>> If the manual in the EXE / DMG are different to the current ZIP'd
>>>>> version, then I think we should package the EXE / DMG version as the
>>>>> new ZIP.
>>>>>
>>>>>>
>>>>>>>
>>>>>>>> What do we call the new package?
>>>>>>>> How about: "audacity-manual-2.1.3-1.zip"
>>>>>
>>>>> Assuming no changes to the content of the manual, I'm +1 for naming
>>>>> it: "audacity-manual-2.1.3-1.zip"
>>>>
>>>> Out of interest, what would the name be if we did change the
>>>> content?
>>>>
>>>> "-1" is ambiguous as to whether it is a just a repacking or a contents
>>>> change. To be unambiguous it could be e.g.
>>>>
>>>> "audacity-manual-2.1.3-repacked.zip".
>>>>
>>>>
>>>>>>>>
>>>>>>>>> If it's not James's decision on hotswap or not, then whose is it?
>>>>>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>>>>>>>> If there is no disagreement about the need for it to be done, then
>>>>>>>> there is no decision to make other than how we go about fixing it.
>>>>>>> Just repackage it correctly with a new file name, as far as I am
>>>>>>> concerned.
>>>>>>>
>>>>>>>
>>>>>>> Gale
>>>>>>
>>>>>> We could fix/clarify the instructions at
>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>>>>>> and that would work just as well as a fix.
>>>>>
>>>>> Not as good a fix, because there's a million copies of the manual in the wild.
>>>>
>>>> +1
>>>>
>>>>
>>>>>> I would presume we will shorten the install path for 2.2.0 help and
>>>>>> clarify those instructions for 2.2.0 to say where the help files should
>>>>>> end up.
>>>>>
>>>>> +1
>>>>
>>>> Please make a specific proposal. We don't want A.N.Other extraction
>>>> utility spewing help files into the root of the app.
>>>>
>>>>
>>>>>
>>>>>>
>>>>>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so that
>>>>>> users who just fetch and unzip it have some instructions on how to make
>>>>>> Audacity find it.
>>>>>
>>>>> +1
>>>>> or we could call it "INSTALL.TXT" or "README.TXT" (more traditional).
>>>>
>>>> +1.  So does that instructions file need to be committed to the "help" folder
>>>> in Git?
>>>>
>>>>
>>>>>> I took my RM-is-God hat off after 2.1.3 release was announced, so you
>>>>>> shouldn't be waiting on me for approval.
>>>>
>>>> James. you or someone who was helping you mispackaged the
>>>> Manual.
>>>>
>>>> We are all human (and no-one in QA checked, given this has never
>>>> gone wrong before), but should it not be you or your helper who
>>>> fixes it?
>>>>
>>>> I say we should repackage it, contents and page titles unchanged.
>>>>
>>>>
>>>> Gale
>>>>
>>>>>> I'd imagine most users who
>>>>>> download the manual separately are accessing it directly rather than
>>>>>> from within Audacity
>>>>>> - and also that the vast majority of linux users use the manual on line.
>>>>>
>>>>> Looks to me like we need to do more to encourage users to use the manual ;-)
>>>>>
>>>>> As a regular user of open source software, our manual really is a huge
>>>>> and fantastic selling point for Audacity. History is littered with
>>>>> software that died through lack of good documentation. We should make
>>>>> much of it.
>>>>>
>>>>> Steve
>>>>>
>>>>>>
>>>>>> --James.
>>>>>>
>>>>>
>>>>> ------------------------------------------------------------------------------
>>>>> Check out the vibrant tech community on one of the world's most
>>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>>> _______________________________________________
>>>>> Audacity-quality mailing list
>>>>> [hidden email]
>>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>>
>>>> ------------------------------------------------------------------------------
>>>> Check out the vibrant tech community on one of the world's most
>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>>> _______________________________________________
>>>> Audacity-quality mailing list
>>>> [hidden email]
>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>
>>>
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> [hidden email]
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Manual ZIP file packed incorrectly

Stevethefiddle
Please test this version: https://www.sendspace.com/file/typgoz

Steve

On 11 May 2017 at 13:22, David Bailes <[hidden email]> wrote:

> On Thu, May 11, 2017 at 10:03 AM, Steve the Fiddle
> <[hidden email]> wrote:
>>
>> On 11 May 2017 at 02:39, Cliff Scott <[hidden email]> wrote:
>> > Ok. I see what you are referring to. Yes it is as you expected,
>> > i.e.Audacity Development Manual.
>> >
>> > Cliff
>> >
>> >> On May 10, 2017, at 8:00 PM, Gale Andrews <[hidden email]>
>> >> wrote:
>> >>
>> >> Hi Cliff,
>> >>
>> >> Thanks, but no we are talking about the page title. If your browser
>> >> does not show page titles (many don't these days at default
>> >> settings), you can examine the source code of the file to confirm.
>>
>> Also, if the CSS theme is off, then "From Audacity Development Manual"
>> is displayed as a sub-heading.
>> I discovered that accidentally while moving folders to make Help work
>> in Audacity (I had the "m" folder in the wrong location).
>> Do screen readers read it?
>
>
> If text is set to display:none in the css, it's not read by screen readers,
>
> David.
>
>>
>>
>> Steve
>>
>> >>
>> >>
>> >>
>> >> Gale
>> >>
>> >>
>> >> On 10 May 2017 at 22:36, Cliff Scott <[hidden email]> wrote:
>> >>>
>> >>>> On May 10, 2017, at 2:54 PM, Gale Andrews <[hidden email]>
>> >>>> wrote:
>> >>>>
>> >>>> On 10 May 2017 at 10:25, Steve the Fiddle <[hidden email]>
>> >>>> wrote:
>> >>>>> On 10 May 2017 at 09:27, James Crook <[hidden email]> wrote:
>> >>>>>> On 5/10/2017 2:12 AM, Gale Andrews wrote:
>> >>>>>>> On 10 May 2017 at 01:32, Steve the Fiddle
>> >>>>>>> <[hidden email]> wrote:
>> >>>>>>>> On 10 May 2017 at 00:22, Gale Andrews <[hidden email]>
>> >>>>>>>> wrote:
>> >>>>>>>>> James, it's broken for all users who intend to locate the
>> >>>>>>>>> standalone zipped Manual from within Audacity.
>> >>>>>>>>>
>> >>>>>>>>> It would be good if a script could automate what is required,
>> >>>>>>>>> but the "zipping" part of
>> >>>>>>>>> http://wiki.audacityteam.org/wiki/Create_Local_Manual
>> >>>>>>>>> was not followed as it should have been (it's a clear part
>> >>>>>>>>> of http://wiki.audacityteam.org/wiki/Release_Process).
>> >>>>>>>> I think we can make the instruction clearer.
>> >>>>>>>> On Linux (Xubuntu) it is necessary to move the "manual" folder
>> >>>>>>>> (downloaded with the wiki2htm.sh script) into an empty "help"
>> >>>>>>>> folder
>> >>>>>>>> before zipping it (with "Archive Manager").
>> >>>>>>> Surely all a developer on any platform needs to know is the
>> >>>>>>> structure that is wanted?
>> >>>>>> I think the instructions on installing the manual (what paths to
>> >>>>>> end up
>> >>>>>> with after unzipping) and building the manual (the zipping part)
>> >>>>>> both
>> >>>>>> could be improved.  My install of RC3 (from innosetup) has the
>> >>>>>> manual in
>> >>>>>> the correct position with the correct name, (i.e. not development
>> >>>>>> manual).
>> >>>>>>
>> >>>>>> Why do we have a ./help/manual/ in the path and not just ./help or
>> >>>>>> just
>> >>>>>> ./manual?  It seems an extra level that serves no purpose and just
>> >>>>>> makes
>> >>>>>> manual installation harder.
>> >>>>>
>> >>>>> I agree, the path to the manual is overly complex. I suspect that it
>> >>>>> came about due to differences in archive extraction apps, with some
>> >>>>> extracting the archive contents directly into the specified
>> >>>>> location,
>> >>>>> and others extracting into a folder in the specified direction.
>> >>>>
>> >>>> Those differences seem to me to be compelling reason not to
>> >>>> "improve" the developer instructions on building the Manual by
>> >>>> giving per app instructions. .
>> >>>>
>> >>>> The developer can choose his app on his particular OS to package
>> >>>> the zip, knowing that he has to produce a ZIP that:
>> >>>>
>> >>>>  "should produce a "help" folder with the "manual" folder inside
>> >>>> that".
>> >>>>
>> >>>> All you need to do (for example) is to right-click the ZIP file you
>> >>>> packaged > 7-Zip > Open Archive and check you are looking at the
>> >>>> "help" folder.
>> >>>>
>> >>>>
>> >>>>> what we want to avoid is spewing a mass of files into a location
>> >>>>> where
>> >>>>> other (non-manual) files exist.
>> >>>>>
>> >>>>> My guess is that index.html and quick_help.html are outside of the
>> >>>>> main "manual" folder so that the can be found easily by anyone
>> >>>>> wanting
>> >>>>> to access the manual directly (rather than from Audacity).
>> >>>>
>> >>>>>>>>> If the corrected ZIP file needs to be renamed then
>> >>>>>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html.
>> >>>>>>>>>
>> >>>>>>>>> would have to change its link (that's the online copy of the
>> >>>>>>>>> released Manual).  However it's a packaging change only, not
>> >>>>>>>>> a change of content.
>> >>>>>>>> The 'packaging' (the zipping process) is certainly wrong.
>> >>>>>>>> Are the contents correct? I notice that the index page says:
>> >>>>>>>>
>> >>>>>>>> "Audacity Manual Contents
>> >>>>>>>>> From Audacity Development Manual"
>> >>>>>>> As I said before, that happens because the released Manual
>> >>>>>>> is dumped from the development Manual. When users visit
>> >>>>>>> the development Manual, we want the site title to say
>> >>>>>>> "Audacity Development Manual" so they can distinguish it
>> >>>>>>> from the online released Manual.
>> >>>>>>>
>> >>>>>>> So when we dump, we change the alphamanual site title
>> >>>>>>> to "Audacity Manual" and while we wait to see if the RC will
>> >>>>>>> pass, we change it back to "Audacity Development Manual" .
>> >>>>>>> When we have a protracted release with many RCs, it's
>> >>>>>>> easy to forget to change the alphamanual site title each time
>> >>>>>>> the Manual is dumped.
>> >>>>>>>
>> >>>>>>> The contents are correct apart from that.
>> >>>>>> I actually did that change to the html after the manual was pulled.
>> >>>>
>> >>>> How did you do that?  I know no way to do that, once the files are
>> >>>> dumped, except text replace in all the files.
>> >>>>
>> >>>> I assumed we were trying to avoid "content changes". If someone
>> >>>> downloaded the ZIP already, deleted it by accident then redownloads
>> >>>> it with the page titles changed to "Audacity Manual", might that not
>> >>>> be confusing? Is it the same Manual they had before?
>> >>>>
>> >>>>
>> >>>>> So does the in-app Windows EXE / Mac DMG manual say "From the
>> >>>>> Development Manual"?
>> >>>>
>> >>>> On Windows the 2.1.3 EXE installer produces page titles that say
>> >>>> "Audacity Development Manual". I am 99% certain that Mac is the
>> >>>> same, from memory.
>> >>>
>> >>> FYI, if you're referring to the Manual that in included in the
>> >>> installer and installed subsequently installed to the local HD, my Mac 2.1.3
>> >>> installation shows "Audacity 2.1.3 Manual" as it should.
>> >>>
>> >>> Cliff
>> >>>
>> >>>>
>> >>>>
>> >>>>>> We
>> >>>>>> could incorporate it in the script that fetches the manual.
>> >>>>>>
>> >>>>>>> I really hope Buanzo will succeed with the Manual clone
>> >>>>>>> because I assume that will solve this site title problem. :=)
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>> I've not seen the Windows version, but if that's the same, then I
>> >>>>>>>> think we need to stick with that even though it looks a bit
>> >>>>>>>> weird.
>> >>>>>>> Yes.
>> >>>>>> Why not fix it?
>> >>>>
>> >>>> ROI could be another reason.
>> >>>>
>> >>>> The better idea would be to move to the Manual clone. Then it should
>> >>>> be easier to avoid this site title renaming problem *and* have a
>> >>>> Search
>> >>>> box in the online released Manual.
>> >>>>
>> >>>>
>> >>>>>> If there is a new version of the file to download shouldn't we fix
>> >>>>>> that too?
>> >>>>>
>> >>>>> I would hope that we can avoid going through a "release process" for
>> >>>>> a
>> >>>>> new version of the manual.
>> >>>>> Once you say "we'll just fix this little bit", then surely it makes
>> >>>>> sense to also fix "that little bit", and perhaps "that other little
>> >>>>> bit"...
>> >>>>>
>> >>>>>> From a support point of view, it is much 'cleaner' if all versions
>> >>>>>> of
>> >>>>> "the Audacity 2.1.3 manual" are identical. I'm therefore strongly in
>> >>>>> favour of 'only' repacking the manual, assuming that the manual in
>> >>>>> the
>> >>>>> EXE / DMG bundles are the same as the current ZIP'd manual.
>> >>>>
>> >>>> +1.
>> >>>>
>> >>>>> From James's description, the EXE/DMG contents are the same
>> >>>> as that of the ZIP, if we don't retitle the pages to "Audacity
>> >>>> Manual".
>> >>>>
>> >>>>
>> >>>>> If the manual in the EXE / DMG are different to the current ZIP'd
>> >>>>> version, then I think we should package the EXE / DMG version as the
>> >>>>> new ZIP.
>> >>>>>
>> >>>>>>
>> >>>>>>>
>> >>>>>>>> What do we call the new package?
>> >>>>>>>> How about: "audacity-manual-2.1.3-1.zip"
>> >>>>>
>> >>>>> Assuming no changes to the content of the manual, I'm +1 for naming
>> >>>>> it: "audacity-manual-2.1.3-1.zip"
>> >>>>
>> >>>> Out of interest, what would the name be if we did change the
>> >>>> content?
>> >>>>
>> >>>> "-1" is ambiguous as to whether it is a just a repacking or a
>> >>>> contents
>> >>>> change. To be unambiguous it could be e.g.
>> >>>>
>> >>>> "audacity-manual-2.1.3-repacked.zip".
>> >>>>
>> >>>>
>> >>>>>>>>
>> >>>>>>>>> If it's not James's decision on hotswap or not, then whose is
>> >>>>>>>>> it?
>> >>>>>>>>> It's 2.1.3 release and James was 2.1.3 RM.
>> >>>>>>>> If there is no disagreement about the need for it to be done,
>> >>>>>>>> then
>> >>>>>>>> there is no decision to make other than how we go about fixing
>> >>>>>>>> it.
>> >>>>>>> Just repackage it correctly with a new file name, as far as I am
>> >>>>>>> concerned.
>> >>>>>>>
>> >>>>>>>
>> >>>>>>> Gale
>> >>>>>>
>> >>>>>> We could fix/clarify the instructions at
>> >>>>>> http://manual.audacityteam.org/man/unzipping_the_manual.html
>> >>>>>> and that would work just as well as a fix.
>> >>>>>
>> >>>>> Not as good a fix, because there's a million copies of the manual in
>> >>>>> the wild.
>> >>>>
>> >>>> +1
>> >>>>
>> >>>>
>> >>>>>> I would presume we will shorten the install path for 2.2.0 help and
>> >>>>>> clarify those instructions for 2.2.0 to say where the help files
>> >>>>>> should
>> >>>>>> end up.
>> >>>>>
>> >>>>> +1
>> >>>>
>> >>>> Please make a specific proposal. We don't want A.N.Other extraction
>> >>>> utility spewing help files into the root of the app.
>> >>>>
>> >>>>
>> >>>>>
>> >>>>>>
>> >>>>>> Possibly we should put a HELP_LOCATION.TXT in the top of the zip so
>> >>>>>> that
>> >>>>>> users who just fetch and unzip it have some instructions on how to
>> >>>>>> make
>> >>>>>> Audacity find it.
>> >>>>>
>> >>>>> +1
>> >>>>> or we could call it "INSTALL.TXT" or "README.TXT" (more
>> >>>>> traditional).
>> >>>>
>> >>>> +1.  So does that instructions file need to be committed to the
>> >>>> "help" folder
>> >>>> in Git?
>> >>>>
>> >>>>
>> >>>>>> I took my RM-is-God hat off after 2.1.3 release was announced, so
>> >>>>>> you
>> >>>>>> shouldn't be waiting on me for approval.
>> >>>>
>> >>>> James. you or someone who was helping you mispackaged the
>> >>>> Manual.
>> >>>>
>> >>>> We are all human (and no-one in QA checked, given this has never
>> >>>> gone wrong before), but should it not be you or your helper who
>> >>>> fixes it?
>> >>>>
>> >>>> I say we should repackage it, contents and page titles unchanged.
>> >>>>
>> >>>>
>> >>>> Gale
>> >>>>
>> >>>>>> I'd imagine most users who
>> >>>>>> download the manual separately are accessing it directly rather
>> >>>>>> than
>> >>>>>> from within Audacity
>> >>>>>> - and also that the vast majority of linux users use the manual on
>> >>>>>> line.
>> >>>>>
>> >>>>> Looks to me like we need to do more to encourage users to use the
>> >>>>> manual ;-)
>> >>>>>
>> >>>>> As a regular user of open source software, our manual really is a
>> >>>>> huge
>> >>>>> and fantastic selling point for Audacity. History is littered with
>> >>>>> software that died through lack of good documentation. We should
>> >>>>> make
>> >>>>> much of it.
>> >>>>>
>> >>>>> Steve
>> >>>>>
>> >>>>>>
>> >>>>>> --James.
>> >>>>>>
>> >>>>>
>> >>>>>
>> >>>>> ------------------------------------------------------------------------------
>> >>>>> Check out the vibrant tech community on one of the world's most
>> >>>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> >>>>> _______________________________________________
>> >>>>> Audacity-quality mailing list
>> >>>>> [hidden email]
>> >>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>> >>>>
>> >>>>
>> >>>> ------------------------------------------------------------------------------
>> >>>> Check out the vibrant tech community on one of the world's most
>> >>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> >>>> _______________________________________________
>> >>>> Audacity-quality mailing list
>> >>>> [hidden email]
>> >>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>> >>>
>> >>>
>> >>>
>> >>> ------------------------------------------------------------------------------
>> >>> Check out the vibrant tech community on one of the world's most
>> >>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> >>> _______________________________________________
>> >>> Audacity-quality mailing list
>> >>> [hidden email]
>> >>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>> >>
>> >>
>> >> ------------------------------------------------------------------------------
>> >> Check out the vibrant tech community on one of the world's most
>> >> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> >> _______________________________________________
>> >> Audacity-quality mailing list
>> >> [hidden email]
>> >> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>> >
>> >
>> >
>> > ------------------------------------------------------------------------------
>> > Check out the vibrant tech community on one of the world's most
>> > engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> > _______________________________________________
>> > Audacity-quality mailing list
>> > [hidden email]
>> > https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Audacity-quality mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Audacity-quality mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Audacity-quality mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/audacity-quality
12
Loading...