Difference between revisions of "Talk:Wording"

From Audacity Wiki
Jump to: navigation, search
(reply to Peter)
(What is wording?)
 
(29 intermediate revisions by 3 users not shown)
Line 2: Line 2:
 
{{note|Old discussions should probably be removed from the main page in time, and archived here, and later removed altogether.  That's not the 'done' items, rather it's the items for which we decide wording after some discussion. }}
 
{{note|Old discussions should probably be removed from the main page in time, and archived here, and later removed altogether.  That's not the 'done' items, rather it's the items for which we decide wording after some discussion. }}
 
__TOC__
 
__TOC__
{{note|1=
 
'''Rules for our Text'''
 
See the [http://alphamanual.audacityteam.org/man/Consistency Consistency] page in the Manual and [[Guidelines on capitalization in Audacity dialogs and messages]].
 
*US spelling is to be used throughout.
 
*Do we have any consistent rules about text?  For example, we always capitalize 'Audacity'. 
 
*Do we capitalize, single quote or double quote menu item names when used in text?
 
**<font color="green"> Capitalize and double quote e.g. "Effect" Menu? [GA] </font>
 
*We use '>' when describing menu/submenu sequences?.
 
*Do we have an upper limit on how much text we will put on a button or on a radio button?
 
**<font color="green"> Does it depend on the dialog in question to some extent? [GA]  </font>
 
}}
 
  
== Preferences ==
+
==Menu changes suggested for sorting tracks==
The descriptor for Auto-select states:  ""'''Select then act on entire project, if no audio selected'''"
 
  
This descriptor is no longer accurate or entirely true and can be misleading ''(except maybe in the usecase of a single audio track)''.
+
{{note|Robert Hänggi and Cliff Scott have proposed the following change to two menu strings.  This change is out of scope of the current changes here on the Wording page, but could be considered at the same time as the changes requested above are made.
 +
*'''Peter 07Feb18:''' I prefer the current formualtion when I look at it in context on-screen in the app.
 +
{{note|Robert wrote: ''"This is a point that bothers me at other places too.  I've already given a nasty German example: "Ansicht"->"Werkzeugleisten"->"Werkzeuge-Werkzeugleiste", i.e. toolbars menu under view."'' }} }}
  
The new behaviors are probably too complex to expect to be able to be expressed adequately in a Preferences dialog descriptor without becomining very verbose.
+
{| class="wikitable" width="50%" style="background:#EEEEEE; padding:10px"
 +
|-valign=top align="left"
 +
! Existing menu string !! Proposed revised menu string
 +
|-valign=top
 +
| width="50%"|Tracks > Sort Tracks > by Start Time...
 +
|'''Tracks > Sort By > Start time...'''
 +
|-
 +
|Tracks > Sort Tracks > by Name...
 +
|'''Tracks > Sort By > Name...'''
 +
|}
  
*'''Peter 31May17:''' I would favour the simple "'''Auto-select'''", now that we have the iconic help button in the Preferences dialogs to lead the user to the full explanation in the Manual.<p>''To me auto-select seems quite clear in its basic intent even if one does not understand the details.''</p>
+
== References to audacity.sourceforge.net ==
*'''James 1Jun17:''' I favour '''Auto-select''' too.  I think for noobs that know what a selection is, "Auto-select" is enough to convey the general idea of what it might be for.  For noobs who don't know what a selection is help is by far the best way to educate them.
+
{{ednote|'''James 23Jan18:''' These changes aren't ready to apply to Audacity code.  For example, we haven't decided on changing the DTD.}}
*'''Gale 03Jun17:''' Let's look at this holistically (James's complete list of shortened preferences labels). I'll take a look soon.  
+
The following files in our codebase contain one or more references to audacity.sourceforge.net:
*'''Gale 04Jun17:''' My somewhat less aggressive take on it: https://github.com/windinthew/audacity/commit/a582d05 . I have this preference now as "A&uto-select audio for editing".
 
**'''Peter 04Jun17:''' The problem that I have with "Auto-select audio for editing" is that you can do more than just "edit" in particular the unwary user can "Delete" all their audio with the press of a single key.  We know this can (and does) happen from distressed reports we've had on the Forum.
 
** '''Gale 04Jun17:''' Then user should not press delete key again after deleting their selection and should use Undo if they do delete twice. Or, I'd be fine if delete is made one of the actions that auto-select does not work on. It was you who wanted us to add "then act" to the current wording, because it was misleading without. <p>It may be possible to trim some prefs texts a little shorter still *if* we have in-line contextual help. I see no guarantee that will happen soon, given the issues with anchor links, so the texts should have some amount of meaning until then. Do you have input on my other suggestions for shortening, or James's https://github.com/audacity/audacity/commit/938c42 ? If so, perhaps start a -quality topic. </p>
 
***'''Peter 04Jun17:''' I can't look at James' shortening changes till I get home on Tuesday, as I only have the Macbook here in Zurich - and there hasn't  been a Mac nightly posted since 21May17 as you know.
 
***'''Gale 05Jun17:''' Well you could always read the diffs I guess if you have trouble sleeping. My attempt is not hugely different to James's.
 
  
== Audacity Built-in effects, generators and analyzers ==
+
* \lib-src\FileDialog\configure
Change:
+
* <del>\lib-src\libnyquist\README.txt</del>
Effect > Audacity  to '''Effect > Built-in'''
+
* \lib-src\libsndfile\ChangeLog
Analyze > Audacity  to '''Analyze > Built-in'''
+
* \lib-src\portmixer\configure
Generate > Audacity  to '''Generate > Built-in'''
+
* \src\export\ExportFFmpegDialogs.cpp
 +
* \src\xml\audacityproject.dtd
 +
* \src\Project.cpp
 +
* \tests\ProjectCheckTests\missing_aliased_and_auf_files.aup
 +
* \tests\ProjectCheckTests\missing_blockfile.aup
 +
* \tests\ProjectCheckTests\orphaned_blockfiles.aup
  
Built-in is what we normally refer to them as in documentation e.g. [http://alphamanual.audacityteam.org/man/Effect_Menu#built-in this page in the Manual]
+
==TCP buttons & sliders==
 +
'''Peter 14Jul17:''' My suggestions for mouse-over hovertext tooltips. ''Note carefully that there is no full-stop/period at the end of each descriptor (this is how Connie like things to be'':
 +
*'''Close''':  Delete the track
 +
*'''Track name''':  Right-click for menu options
 +
*'''Mute''':  Click to silence this track when playing
 +
*'''Solo''':  Click to play just this track
 +
*'''Collapse''':  Collapse or restore the height of the track.
 +
*'''Expand''':  Collapse or restore the height of the track
 +
*'''Gain slider''':  Gain slider for adjusting the volume of the track
 +
*'''Pan slider''': Pan slider to position the audio of this track in the stereo sound stage.
 +
{{note|Yes, I know the mute/solo can be more complex - bt this covers the default mode now.  More sophisticated users will not really need the tooltip as they will have already explored the preferences - and hopefully the Manual.}}
  
Consider too, the Nyquist effects are also part of Audacity - part of the Audacity bundle that you get when you download and install Audacity.
 
  
*'''Peter 25Mar17:''' I support thisSteve added his support by email
+
==Just a wording changeReally?==
  
== Edit > Select > Ends to zero Crossings ==
+
*'''cleaned''' ''(the output folder created by a Macro)'' should be renamed '''Macro-output'''{{alert|1=This change of 'cleaned' is '''not''' a wording change.  It is a change in behaviour as to where Audacity stores files.  It does not really belong on this page any more than using or not using the documents folder does.  I'll see about making it, but I don't want using this page for these kinds of changes to become a habit. (James, RM hat on, and looking fierce)
I suggest this says Select > "At Zero Crossings". The changed wording is misleading/confusing when there is only a cursor.
+
*'''Peter 03Apr18:''' (with QA hat on - ''ignoring fierce looks - and shouting ...'') sorry but what is suggested here '''''is''''' just a simple wording change to make the nomenclature a little more meaningful.  <p>This change request does nothing to suggest changes to '''''where''''' the folder is stored. There have been such requests on the Forum, but rightly, as you say James, that is not a topic for this page.</p><p> But thank you for saying you may look at doing this :-) </p>
*'''Peter 24Mar17:''' +1
+
}}
*'''Gale 27Mar17:''' This request is now being handled in the menu changes spreadsheet we are working on.  
 
  
== Incomplete message about Draw Tool ==
+
*'''James 04Apr19:''' This really is more than a wording change.  It is like saying changing C:\Program Files (x86)\ to C:\Apps\ is 'just a wording change'.  It does not just affect the UI, but affects program behaviour.  As an example of the kind of potential problem, consider a Spanish translator who translates 'App' to 'Aplicación'.  We now have a unicode character in a path name - which some systems throw a wobbly at.  You can see too that [https://github.com/audacity/audacity/commit/37e61ab1c21715b6e770daf3f55aded01bb9db81 the change entails not just a change to a string]. So whilst I am OK with making the change, and have done so, I reiterate that it is not simply a wording changeAs RM I do not want directory renaming changes, or changes to a file names or their extensions, or to file patterns (such as *.png|*.jpeg|*.gif) or to names of external programs to invoke, to be classified as 'wording changes'.
Draw Tool now works in Waveform (dB) view, but the message when you use Draw Tool in Spectrogram view was changed in https://github.com/audacity/audacity/commit/5abbd4 from "To use Draw, choose 'Waveform' or 'Waveform dB' in the Track Drop-down Menu." to the less correct "To use Draw, choose 'Waveform' in the Track Drop-down Menu."
 
   
 
So, change the message back to "To use Draw, choose 'Waveform' or 'Waveform dB' in the Track Drop-down Menu."
 
*'''Peter 24Mar17:''' +1 for Gale's suggestion
 
  
== distinction between Open Project & Import audio file ==
+
==Modernization: program to application ==
{{note|'''Peter 05Mar17:''' Surely this is far more than a "wording" issueIt is fundamental to how we view and manage native data (projects) and non-native data (audio files). It has been discussed elswhere with no resolution. I'm not convinced this diuscussion belongs on the Wording>Talk page.  If we want to keep it then maybe we should be writing a ProposalThis old discussion could then be transferred to such a proposal's talk page. }}
+
{{advice|The 'Program' to 'Application' change is almost agreed<br>  (a) <s>because there may be more places not yet identified where it needs to change.<br> (b) because there are still alternative suggested wordings being suggested.</s>  <br>RM for 2.1.3 (James) is OK with this change being made, but believes that 'Program' includes 'Application' so the current wording does not have to change.}}
 +
{{ednote|'''Gale 01Nov16:''' Replying to James's "alert", I did search the code and I think all instances of "program" are listed here. I don't know when the freeze is but I'm prepared to commit my take on this, leaving out the few that are unclear. We can always change those others later. I think this change is moderately important in making Audacity look less dated.
 +
* '''JC:''' Invitation to go ahead, so that we can clear this item off this page and demote the wording bugzilla item from P2.
 +
* '''Gale 02Nov16:''' There is no implied Bugzilla rating for items on this page as far as I know, unless P2 is assumed unless stated otherwise. An embarrassing typo could be P1.
 +
* '''James 03Nov16:''' Ideally the Bugzilla bug's rating is the 'highest' of the rating for any of the agreed wording changes on this page. A P1 embarrassing typo should either be fixed immediately, or Bug 1427 should be raised to P1.  Clearly a P1 typo should block release! If we've only got unagreed changes in this queue, Bug 1427 should drop to P4 (or be marked DEVEL-FIXMADE)That tells RM that QA sees no Wording changes serious enough to block on.  Generally RM would want this page 'empty' and Bug 1427 DEVEL_FIXMADE or P4 before translation freeze.}}  
 +
Following recent QA discussion on email it was decided to modernize Audacity by changing Program to application as more contemporary usage throughout the documentation.  Most of the changes in the Manual have been done, but there remain places in the code that need to be changed before we can update their associated pages in the Manual.
  
*'''Peter 07Mar17:''' My views on this:
+
* '''Gale 12May16:''' Where is that discussion on http://audacity.238276.n2.nabble.com/audacity-quality-f7561562.html ? I only see an offlist discussion.  There are more places in the interface than you mention:
*#<strike>I agree with Gale and Ed that the ellispes should not be there on the Open/Import dialogs. None of the other apps I use has an ellipsis in their file>open dialogs.</strike>
+
** src/AboutDialog.cpp:215 "Audacity is a free program..."  
*#<strike>I agree that the current dialog title invoked by File>Open is very misleading. It says "Select one or more audio files..." and thus does not indicate that the Open applies to Projects too ''which must be considered one of its main purposes, if not its primary purpose'' - so at the very least this should be retitled as Gale suggested 5 years ago to "'''Select one or more audio or project files'''" or better still to "'''Select one or more Audacity Projects or audio files'''" ''(bearing in mind that an Audacity Project is not a "file" to be opened)''</strike>
+
** src/AboutDialog.cpp:524 "Program build date"
*#With regard to the  Import - since it is not possible to Import an Audacity it would make a lot of sense if any default on invoking this dialog the "Files of type" dropdown should show "All supported files" rather than "All files" - ''and yes, I realize that this point is a programming issue and not a simple Wording issue''.
+
** src/effects/nyquist/Nyquist.cpp:2056 "Current program has been modified"
*#But fundamantally I strongly '''''remain''''' of the ''(possibly unfashionable)'' purist view that Open and Save should be reserved for native data i.e. Audacity Projects and Import/Export should be reserved for non-native data i.e. audio files, label files etc.
+
** src/effects/vamp/VampEffect.cpp:622 "Program"
**Since we appear to have definite consensus on #1 above and consensus that #2 requires some change ''(either Gale's wording from 5 years ago or my recent suggestion)'' I propose to move these two items in due course ''(post 2.1.3 release probably)'' to the Wording page.
+
** src/export/Export.cpp:636 "Normally these files end in \".%s\", and some programs will not open files..."
***'''Peter 24Mar17:''' Items 1 and 2 transferred to the Wording page - removed the P2
+
** src/prefs/ThemePrefs.cpp:101 "when the program starts up"
 +
***'''Peter 13May16:''' Not on nabble because a limited Quality Assurance discussion (DL: Gale, Steve, Peter, Bill - as active Manual editors. And yes I realized that there might well be other places in the code that I had not been able to discover, thanks for that digging.
  
 +
===Export Audio dialog===
 +
The "Save as type" dropdown
  
 +
'''Current text:'''
  
 +
"(external program)"
  
'''initial report by Ed Nov 2011'''
+
'''Suggested replacement:'''  
If Audacity keeps the distinction between "Open Project" and "Import audio file" the Open File Dialog might have two different potential titles. Currently, "_("Select one or more audio files...")" is used for both (and as it is the Dialog title probably should not have a trailing ellipsis--see MS Word's Open Dialog which does not).
 
Proposed:
 
*If current distinction between Open & Import persists:
 
**Open Project: "_("Open one or more Audacity Projects")"
 
**Import audio: "_("Import one or more audio files")"
 
*otherwise:
 
**"_("Open")"
 
Note that when File > Import > Labels... is chosen its Dialog title is distinct: "Select a text file containing labels..." (but again contains a spurious  ellipsis). Similarly, Import MIDI and Raw both have distinct titles. In the MIDI case, it says "Select a MIDI file..." in which the "a" properly implies you may only Import one MIDI file via the dialog. However, in the Raw case it says "Select any uncompressed audio file..." which is slightly ambiguous--maybe "any" should be "an".
 
  
<ul><li> '''Gale 12Nov11:''' <p>If things stay as they are, File > Open can't be titled "Open one or more Audacity Projects" as that dialogue opens audio files as well. "Select" covers both open and import, but certainly the current wording for "Open" that implies it does not open projects isn't perfect - it would ideally say "Select one or more audio or project files". Would  having individual text for "open" and "import audio" mean a coding change (are the dialogues common)?</p><ul><li>I agree there should not be ellipses in Open/Save file dialogues.
+
"(external application)"
<li> I agree a dialogue restricted to single file selection should have "a" or "an".</ul></ul><ul style="list-style-image: none; list-style-type: none">The dialogue for importing an EQ Curve file is correct on both counts ("an" and no ellipsis).The above two bullet points could I think go on the article page - can you identify all the culprits?</ul>
+
*'''Steve 18May16:''' An "application" usually refers to a computer program with an interface. At the least, an "application" usually refers to a computer program that has interactive input and/or output (usually a "GUI" but may be an "application command line interface"). In this case we are referring to a "command line program" that takes parameters only from the initial command. To simplify this point "C-Dex", "RazorLame", "WinLame" and similar are "applications", whereas "LAME" is a "program".
 +
* '''Gale 18May16:''' When saving/loading VST presets these are called "programs" in our interface, but I think "program" is correct there. I am less sure "(external application)" is wrong. After all it can be used in a terminal window, it's Audacity's choice not to do so. And it is an EXE file on Windows. If it was my choice I would allow "(external application)". That apart, is there any consensus for these changes? Steve had not spoken before, so I've done nothing about it. I'm about +0.8 - users on older Windows may be confused - but that problem will decline.
 +
*'''Peter 18May16:''' My understanding was that on the limited DL of Gale, Steve and myself we had consensus on this, Bill was included too but made mo comment.  The basic problem started when I discovered a few weeks ago that the Manual was inconsistent a few weeks ago using both forms in different places.  I wrongly assumed it was confined to the Manual (hence the limited DL) and started work on the changes to bring it into line with "application".  Part way through I realized that it affected the Audacity application itself with "program" used in some dialogs. Like Gale I would opt for "(external application)" in this dialog.  I was, and am still, loath to widen this out to a Team vote or a devel list discussion over such a relatively trivial issue.
 +
** '''Gale 18may16:''' I am unsure in what context Nyquist.cpp:2056 "Current program has been modified" and VampEffect.cpp:622 "Program" appear. I guess Steve knows the answer about Nyquist. Otherwise, those two look as if they could be left as is.
 +
*** '''Steve 01Feb17:''' Re. Nyquist.cpp: "Current program has been modified", "program" is appropriate as it refers to the Nyquist script code.
  
'''Ed 12Nov11:''' It is easy to set the open dialog title conditionally based on if it is being called via OnOpen() or OnImport() from the menu; I've already patched my personal version to do so. As for IDing "all" culprits, I could try but don't really expect to be exhaustive--I just don't use all the more esoteric tools. I see no easy way of searching the source text to find them.
+
===Export Multiple dialog===
* '''Gale 15 Nov11:''' OK, but that is still programming rather than simply "wording". Would searching for "FileDialog" find all the titles?
+
The "Format:" dropdown
**'''Ed 14Nov11 (PST no I'm not seeing into the future <grin> ):''' I admit "title conditionally based" is 4 or 5 lines of new code but trivial code. As for searching out all the ellipses in dialog titles it is not good enough to search FileDialog as by the time you get there the string is passed as a variable. One would need to manually inspect all Effects and fix as needed. There are about 40 built-ins to check and 18 supplied Nyquists. I suppose that if I got a commitment from someone with commit rights I could be talked into doing a patch for the built-ins. I could also look at the Nyquist files too.
 
[[image:OpenImport.png]]<br>
 
  
 +
'''Current text:'''
  
 +
"(external program)"
  
==Old Discussions==
+
'''Suggested replacement:'''
  
=== playthrough ===
+
"(external application)"
{{note|'''Peter 05Mar17:''' This may have been the case 5 years ago, but googling now will give you many occurences - mostly in gamer-speak but also in regard to audio,  I see no reason to change this in Audacity. I moved this to the the Old Discussions section of this page.}}
 
"playthrough" is not listed in any online dictionary as a single word. I found:
 
  src\Menus.cpp(637):  c->AddCheck(wxT("SWPlaythrough"), _("Software Playthrough (on/off)"), FN(OnToggleSWPlaythrough), 0);
 
  src\prefs\RecordingPrefs.cpp(17):  like playthrough, latency correction, and others.
 
  src\prefs\RecordingPrefs.cpp(63):  S.StartStatic(_("Playthrough"));
 
  src\prefs\RecordingPrefs.cpp(69):      S.TieCheckBox(_("&Hardware Playthrough: Listen while recording or monitoring new track"),
 
  src\prefs\RecordingPrefs.cpp(73):      S.TieCheckBox(_("&Software Playthrough: Listen while recording or monitoring new track"),
 
in SVN HEAD 1Feb12.
 
  
  
=== spurious ellipsis ===
+
===Interface Preferences===
{{note|'''Peter 07Mar17:''' I moved this stale discussion to the "Old Discussions" section.  <p>[[ToDo-2]] It may even be better just to delete it.</p><p> By convention all of Audacity's commands that require further user input via a dialo box carry a trailing ellipsis to indicate that it is not an immediate action command.  Looking at the 2.1.3 effects list (and generators and analyzers) we appear to be consistent in this. </p> }}
+
The checkbox "Show 'How to Get Help' dialog box at program startup"
'''initial report by Ed Nov 2011'''
 
[[media:SpuriousEllipse.patch | patch]]
 
  
Inspecting the header files in src/effects we find the effects classes each of which has a function GetEffectAction() which returns a brief description of what the effect "does". Most have a well formed text but a few have a spurious ellipsis at the end. I propose removing the ellipse.
+
'''Current text:'''
  
Additionally, almost every string is in title case (Every  Word Capitalized Except  the, for and to), so made the two or three exceptions comform.
+
"Show 'How to Get Help' dialog box at program startup"
  
This one is good:
+
'''Suggested replacement:'''
  
class EffectWahwah:public EffectSimpleMono {
+
"Show 'How to Get Help' dialog box at application startup"
[...]
+
or
  virtual wxString GetEffectAction() {
+
"Show 'How to Get Help' dialog box at startup"
      return wxString(_("Applying Wahwah"));
 
  
These all have a spurious ellipsis:
+
The second alternative is consistent with the Welcome message
  
class EffectTruncSilence: public Effect {
 
[…]
 
  virtual wxString GetEffectAction() {
 
      return wxString(_("Truncating Silence..."));
 
  
class EffectSpikeCleaner: public EffectSimpleMono {
+
===Warning dialog===
[…]
+
Low disk space
  virtual wxString GetEffectAction() {
 
      return wxString(_("Applying Spike Cleaner..."));
 
class EffectNormalize: public Effect
 
[…]
 
  virtual wxString GetEffectAction() {
 
      return wxString(_("Normalizing..."));
 
  
class EffectLeveller: public EffectSimpleMono
+
'''Current text:'''
[…]
 
  virtual wxString GetEffectAction() {
 
      return wxString(_("Applying Leveller..."));
 
  
class EffectCompressor: public EffectTwoPassSimpleMono {
+
"Low disk space at program startup"
[…]
 
  virtual wxString GetEffectAction() {
 
      return wxString(_("Applying Dynamic Range Compression..."));
 
class EffectClickRemoval: public Effect {
 
[…]
 
  virtual wxString GetEffectAction() {
 
        return wxString(_("Removing clicks and pops..."));
 
class EffectChangeLength: public Effect {
 
[…]
 
  virtual wxString GetEffectAction() {
 
      return wxString(_("Changing Length..."));
 
  
class EffectAutoDuck: public Effect
+
'''Suggested replacement:'''
[…]
 
  virtual wxString GetEffectAction()
 
  {
 
      return wxString(_("Processing Auto Duck..."));
 
  
 +
"Low disk space at application startup"
  
* '''Gale 11Nov11:''' I don't claim expertise but I disagree with most of this.
 
** While titles should use title-style capitalization, sentence-style capitalization should be used for all other UI elements (though the name of the effect should be capitalised as it is a proper noun). See http://msdn.microsoft.com/en-us/library/windows/desktop/aa974176.aspx#capitalization.
 
** Both the title and label should have the ellipses because an ongoing, incomplete action is still taking place. See http://msdn.microsoft.com/en-us/library/windows/desktop/aa974176.aspx#punctuation
 
<ul style="list-style-image: none; list-style-type: none">
 
I believe the shipped Nyquist effects are correct as per the above bullet points so would all have to be changed if your patch was applied... (ellipses intentional).</ul>
 
  
*'''Ed 11/11/11:'''
+
===Manual pages affected by these proposed changes===
**Do we have a mechanism for creating a "standard" for this? Maybe just a comment in the source, but I do not see where to put it so that it will be seen.
+
*[https://alphamanual.audacityteam.org/man/Export_Multiple Export Multiple]
**In the above built-in effects, the point is that a majority (generally "most") have no ellipsis in the string returned by GetEffectAction(). Either way, they all should be the same and, as it it is description not a title nor label, I agreed with the majority to not have an ellipsis.
+
*[https://alphamanual.audacityteam.org/man/Export_Formats_supported_by_Audacity Export Formats supported by Audacity]
**As for the title case in the description, I would cap the effect title, the first word, no other words and make them all full sentences with a period/full stop at the end; in the above cases I just made the 2-3 which were odd-effect-out match the current style.
+
*[https://alphamanual.audacityteam.org/man/Exporting_to_an_External_Program Exporting to an External Program]
**As for the shipped Nyquist effects, if they have a GetEffectAction() method which returns a string, I believe they should conform to the same standard (once one is made and enforced).
+
*[https://alphamanual.audacityteam.org/man/File_Export_Dialog Export Audio]
***'''Ed:''' I just checked with Steve, the Nyquist guru, and he said: "[code];action "wave-shaping peaks..."[/code]is the message that is shown while the plug-in is processing.". So, if the built-in effects' string is standardized I suppose the shipped Nyquist ones should also conform.
+
*[https://alphamanual.audacityteam.org/man/Tutorial_-_Exporting_to_iTunes Tutorial - Exporting to iTunes]
**@Gale--to what were you disagreeing--my solutions, the MSDN standards or both?
+
*[https://alphamanual.audacityteam.org/man/Warnings_Preferences Warnings Preferences]
**After reading a bunch of style guides and the MSDN guide on using the ellipsis I think I have changed my position. Here is the interactive dialog which is the result of the menu item (which menu item rightly has the ellipsis):<br>
+
*[https://alphamanual.audacityteam.org/man/Subject_Index Subject Index] ??
[[image:Interactive.png]]<br>
 
  
Here is the current progress dialog:<br>
 
[[image:Ellipses.png‎]]<br>
 
I feel that the title of the progress dialog should not have an ellipsis (as the interactive dialog does not). I also feel that the message in the progress dialog should have the ellipsis (which it does not).
 
  
<ul><li> '''Gale 12Nov11:'''
 
<p>In Nyquist plug-ins, ''';name''' (for the titles in the effect and progress dialogues) and ''';action''' (for the progress dialogue description) are both mandatory. Both are always ellipsed e.g.<pre>;name "Notch Filter..."
 
;action "Performing Notch Filter..."</pre></p><p>It is unfortunate that titles in Nyquist effect dialogues are ellipsed (effect dialogues are not "incomplete" or "in progress") but I don't think there is anything that can be done about it unless the Audacity-Nyquist interface changes.</p><p> I was disagreeing with your previous idea of removing ellipses from progress dialogue text (I think both title and description of progress dialogues should be ellipsed). I was disagreeing with your capitalizing descriptions as if they were titles (changing "Removing clicks and pops" to "Removing Clicks and Pops)". "Clicks and Pops" is not the name of an effect. </p><p>I largely agree with MSDN as that is what we have historically followed. We do not have this written down anywhere (as James asked, "do we need a style guide?") hence the hotchpotch here and elsewhere when different developers do things differently. </p><p>
 
Current discussion of possible visual standards are at:
 
http://wiki.audacityteam.org/wiki/Visual_Consistency </p></ul>
 
*'''Ed 14Nov11:''' see above note in re. offer to fix supplied Nyquist.
 
Three of the supplied Nyquist plug-ins already conform to "No ellipsis in dialog title":<br>
 
;name "Sample Analyze Nyquist Plug-in"<br>
 
;action "Analyzing absolutely nothing..."<br>
 
;name "Cross Fade Out"<br>
 
;action "Cross-Fading Out..."<br>
 
;name "Cross Fade In"<br>
 
;action "Cross-Fading In..."<br>
 
* '''Gale 18Nov11:''' The reason those titles (and the menu items) are not ellipsed is that there is no dialogue for those effects. Nothing can be changed for the better in the Nyquist effects by a string change.
 
  
'''Ed 16Nov11:''' I will happily change the others if someone will pre-commit to committing the changes I submit.
+
==Old Discussions==
 
 
'''Steve 18Nov11:''' Are there some Nyquist plug-ins that don't conform?
 

Latest revision as of 09:57, 4 April 2019

If it proves difficult to decide between different alternatives to wording, then we may need to have some kind of voting. I'm not keen on that as it adds overhead and takes longer to sort out. Probably a better scheme is to assume that we will easily reach consensus in most cases, and just flag the difficult cases if they arise. James 13:59, 7 October 2007 (PDT)
Old discussions should probably be removed from the main page in time, and archived here, and later removed altogether. That's not the 'done' items, rather it's the items for which we decide wording after some discussion.

Menu changes suggested for sorting tracks

Robert Hänggi and Cliff Scott have proposed the following change to two menu strings. This change is out of scope of the current changes here on the Wording page, but could be considered at the same time as the changes requested above are made.
  • Peter 07Feb18: I prefer the current formualtion when I look at it in context on-screen in the app.
Robert wrote: "This is a point that bothers me at other places too. I've already given a nasty German example: "Ansicht"->"Werkzeugleisten"->"Werkzeuge-Werkzeugleiste", i.e. toolbars menu under view."
Existing menu string Proposed revised menu string
Tracks > Sort Tracks > by Start Time... Tracks > Sort By > Start time...
Tracks > Sort Tracks > by Name... Tracks > Sort By > Name...

References to audacity.sourceforge.net

James 23Jan18: These changes aren't ready to apply to Audacity code. For example, we haven't decided on changing the DTD.

The following files in our codebase contain one or more references to audacity.sourceforge.net:

  • \lib-src\FileDialog\configure
  • \lib-src\libnyquist\README.txt
  • \lib-src\libsndfile\ChangeLog
  • \lib-src\portmixer\configure
  • \src\export\ExportFFmpegDialogs.cpp
  • \src\xml\audacityproject.dtd
  • \src\Project.cpp
  • \tests\ProjectCheckTests\missing_aliased_and_auf_files.aup
  • \tests\ProjectCheckTests\missing_blockfile.aup
  • \tests\ProjectCheckTests\orphaned_blockfiles.aup

TCP buttons & sliders

Peter 14Jul17: My suggestions for mouse-over hovertext tooltips. Note carefully that there is no full-stop/period at the end of each descriptor (this is how Connie like things to be:

  • Close: Delete the track
  • Track name: Right-click for menu options
  • Mute: Click to silence this track when playing
  • Solo: Click to play just this track
  • Collapse: Collapse or restore the height of the track.
  • Expand: Collapse or restore the height of the track
  • Gain slider: Gain slider for adjusting the volume of the track
  • Pan slider: Pan slider to position the audio of this track in the stereo sound stage.
Yes, I know the mute/solo can be more complex - bt this covers the default mode now. More sophisticated users will not really need the tooltip as they will have already explored the preferences - and hopefully the Manual.


Just a wording change. Really?

  • cleaned (the output folder created by a Macro) should be renamed Macro-output
Warning icon This change of 'cleaned' is not a wording change. It is a change in behaviour as to where Audacity stores files. It does not really belong on this page any more than using or not using the documents folder does. I'll see about making it, but I don't want using this page for these kinds of changes to become a habit. (James, RM hat on, and looking fierce)
  • Peter 03Apr18: (with QA hat on - ignoring fierce looks - and shouting ...) sorry but what is suggested here is just a simple wording change to make the nomenclature a little more meaningful.

    This change request does nothing to suggest changes to where the folder is stored. There have been such requests on the Forum, but rightly, as you say James, that is not a topic for this page.

    But thank you for saying you may look at doing this :-)

  • James 04Apr19: This really is more than a wording change. It is like saying changing C:\Program Files (x86)\ to C:\Apps\ is 'just a wording change'. It does not just affect the UI, but affects program behaviour. As an example of the kind of potential problem, consider a Spanish translator who translates 'App' to 'Aplicación'. We now have a unicode character in a path name - which some systems throw a wobbly at. You can see too that the change entails not just a change to a string. So whilst I am OK with making the change, and have done so, I reiterate that it is not simply a wording change. As RM I do not want directory renaming changes, or changes to a file names or their extensions, or to file patterns (such as *.png|*.jpeg|*.gif) or to names of external programs to invoke, to be classified as 'wording changes'.

Modernization: program to application

Warning icon The 'Program' to 'Application' change is almost agreed
(a) because there may be more places not yet identified where it needs to change.
(b) because there are still alternative suggested wordings being suggested.

RM for 2.1.3 (James) is OK with this change being made, but believes that 'Program' includes 'Application' so the current wording does not have to change.
Gale 01Nov16: Replying to James's "alert", I did search the code and I think all instances of "program" are listed here. I don't know when the freeze is but I'm prepared to commit my take on this, leaving out the few that are unclear. We can always change those others later. I think this change is moderately important in making Audacity look less dated.
  • JC: Invitation to go ahead, so that we can clear this item off this page and demote the wording bugzilla item from P2.
  • Gale 02Nov16: There is no implied Bugzilla rating for items on this page as far as I know, unless P2 is assumed unless stated otherwise. An embarrassing typo could be P1.
  • James 03Nov16: Ideally the Bugzilla bug's rating is the 'highest' of the rating for any of the agreed wording changes on this page. A P1 embarrassing typo should either be fixed immediately, or Bug 1427 should be raised to P1. Clearly a P1 typo should block release! If we've only got unagreed changes in this queue, Bug 1427 should drop to P4 (or be marked DEVEL-FIXMADE). That tells RM that QA sees no Wording changes serious enough to block on. Generally RM would want this page 'empty' and Bug 1427 DEVEL_FIXMADE or P4 before translation freeze.

Following recent QA discussion on email it was decided to modernize Audacity by changing Program to application as more contemporary usage throughout the documentation. Most of the changes in the Manual have been done, but there remain places in the code that need to be changed before we can update their associated pages in the Manual.

  • Gale 12May16: Where is that discussion on http://audacity.238276.n2.nabble.com/audacity-quality-f7561562.html ? I only see an offlist discussion. There are more places in the interface than you mention:
    • src/AboutDialog.cpp:215 "Audacity is a free program..."
    • src/AboutDialog.cpp:524 "Program build date"
    • src/effects/nyquist/Nyquist.cpp:2056 "Current program has been modified"
    • src/effects/vamp/VampEffect.cpp:622 "Program"
    • src/export/Export.cpp:636 "Normally these files end in \".%s\", and some programs will not open files..."
    • src/prefs/ThemePrefs.cpp:101 "when the program starts up"
      • Peter 13May16: Not on nabble because a limited Quality Assurance discussion (DL: Gale, Steve, Peter, Bill - as active Manual editors. And yes I realized that there might well be other places in the code that I had not been able to discover, thanks for that digging.

Export Audio dialog

The "Save as type" dropdown

Current text:

"(external program)"

Suggested replacement:

"(external application)"

  • Steve 18May16: An "application" usually refers to a computer program with an interface. At the least, an "application" usually refers to a computer program that has interactive input and/or output (usually a "GUI" but may be an "application command line interface"). In this case we are referring to a "command line program" that takes parameters only from the initial command. To simplify this point "C-Dex", "RazorLame", "WinLame" and similar are "applications", whereas "LAME" is a "program".
  • Gale 18May16: When saving/loading VST presets these are called "programs" in our interface, but I think "program" is correct there. I am less sure "(external application)" is wrong. After all it can be used in a terminal window, it's Audacity's choice not to do so. And it is an EXE file on Windows. If it was my choice I would allow "(external application)". That apart, is there any consensus for these changes? Steve had not spoken before, so I've done nothing about it. I'm about +0.8 - users on older Windows may be confused - but that problem will decline.
  • Peter 18May16: My understanding was that on the limited DL of Gale, Steve and myself we had consensus on this, Bill was included too but made mo comment. The basic problem started when I discovered a few weeks ago that the Manual was inconsistent a few weeks ago using both forms in different places. I wrongly assumed it was confined to the Manual (hence the limited DL) and started work on the changes to bring it into line with "application". Part way through I realized that it affected the Audacity application itself with "program" used in some dialogs. Like Gale I would opt for "(external application)" in this dialog. I was, and am still, loath to widen this out to a Team vote or a devel list discussion over such a relatively trivial issue.
    • Gale 18may16: I am unsure in what context Nyquist.cpp:2056 "Current program has been modified" and VampEffect.cpp:622 "Program" appear. I guess Steve knows the answer about Nyquist. Otherwise, those two look as if they could be left as is.
      • Steve 01Feb17: Re. Nyquist.cpp: "Current program has been modified", "program" is appropriate as it refers to the Nyquist script code.

Export Multiple dialog

The "Format:" dropdown

Current text:

"(external program)"

Suggested replacement:

"(external application)"


Interface Preferences

The checkbox "Show 'How to Get Help' dialog box at program startup"

Current text:

"Show 'How to Get Help' dialog box at program startup"

Suggested replacement:

"Show 'How to Get Help' dialog box at application startup" or "Show 'How to Get Help' dialog box at startup"

The second alternative is consistent with the Welcome message


Warning dialog

Low disk space

Current text:

"Low disk space at program startup"

Suggested replacement:

"Low disk space at application startup"


Manual pages affected by these proposed changes


Old Discussions