Talk:Wording

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.

dependency dialogs
The Dependency Dialog has: "Save without Copying" which should be in title case as with all other buttons: "Save Without Copying" \src\Dependencies.cpp(292): EVT_BUTTON(wxID_NO, DependencyDialog::OnNo) // mIsSaving ? "Cancel Save" : "Save without Copying" \src\Dependencies.cpp(362): S.Id(wxID_NO).AddButton(_("Save without Copying"));

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

distinction between Open Project & Import audio file
initial report by Ed Nov 2011 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: 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 "a".
 * 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")"

 Gale 12Nov11: 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)? I agree there should not be ellipses in Open/Save file dialogues.  I agree a dialogue restricted to single file selection should have "a" or "an".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?

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.
 * Gale 15 Nov11: OK, but that is still programming rather than simply "wording". Would searching for "FileDialog" find all the titles?
 * Ed 14Nov11 (PST no I'm not seeing into the future ): 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.

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

Additionally, almost every string is in title case (Every Word Capitalized Except  the, for and to), so made the two or three exceptions comform.

This one is good:

class EffectWahwah:public EffectSimpleMono { [...]  virtual wxString GetEffectAction { return wxString(_("Applying Wahwah"));

These all have a spurious ellipsis:

class EffectTruncSilence: public Effect { […]  virtual wxString GetEffectAction { return wxString(_("Truncating Silence..."));

class EffectSpikeCleaner: public EffectSimpleMono { […]  virtual wxString GetEffectAction { return wxString(_("Applying Spike Cleaner...")); class EffectNormalize: public Effect […]  virtual wxString GetEffectAction { return wxString(_("Normalizing..."));

class EffectLeveller: public EffectSimpleMono […]  virtual wxString GetEffectAction { return wxString(_("Applying Leveller..."));

class EffectCompressor: public EffectTwoPassSimpleMono { […]  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 […]  virtual wxString GetEffectAction {     return wxString(_("Processing Auto Duck..."));

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


 * Ed 11/11/11:
 * 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.
 * 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.
 * 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.
 * 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).
 * 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.
 * @Gale--to what were you disagreeing--my solutions, the MSDN standards or both?
 * 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):

Here is the current progress dialog: 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).

 Gale 12Nov11: 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. ;name "Notch Filter..." Current discussion of possible visual standards are at: http://wiki.audacityteam.org/wiki/Visual_Consistency  Three of the supplied Nyquist plug-ins already conform to "No ellipsis in dialog title":
 * action "Performing Notch Filter..."  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.  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.  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.
 * Ed 14Nov11: see above note in re. offer to fix supplied Nyquist.
 * name "Sample Analyze Nyquist Plug-in"
 * action "Analyzing absolutely nothing..."
 * name "Cross Fade Out"
 * action "Cross-Fading Out..."
 * name "Cross Fade In"
 * action "Cross-Fading In..."
 * 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.

Steve 18Nov11: Are there some Nyquist plug-ins that don't conform?

Rules for our Text
Do we have any consistent rules about text? For example, we always capitalise 'Audacity'.

Do we capitalise, single quote or double quote menu item names when used in text?

Capitalise and double quote e.g. "Effect" Menu? [GA]

Do we use '->' or '>' when describing menu/submenu sequences?

'>' (without the quotes) ? [GA]

Do we have an upper limit on how much text we will put on a button or on a radio button?

Does it depend on the dialogue in question to some extent? [GA]