Difference between revisions of "Talk:Wording"

From Audacity Wiki
Jump to: navigation, search
(reply to Peter)
(two items from Talk Page done)
Line 41: Line 41:
  
 
*'''Peter 25Mar17:''' I support this.  Steve added his support by email
 
*'''Peter 25Mar17:''' I support this.  Steve added his support by email
 
== Edit > Select > Ends to zero Crossings ==
 
I suggest this says Select > "At Zero Crossings". The changed wording is misleading/confusing when there is only a cursor.
 
*'''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 ==
 
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 ==
 
== distinction between Open Project & Import audio file ==

Revision as of 01:11, 8 June 2017

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.
Rules for our Text

See the 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?
    • Capitalize and double quote e.g. "Effect" Menu? [GA]
  • 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?
    • Does it depend on the dialog in question to some extent? [GA]

Preferences

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

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.

  • 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.

    To me auto-select seems quite clear in its basic intent even if one does not understand the details.

  • 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.
  • Gale 03Jun17: Let's look at this holistically (James's complete list of shortened preferences labels). I'll take a look soon.
  • 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.

      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.

      • 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

Change: Effect > Audacity to Effect > Built-in Analyze > Audacity to Analyze > Built-in Generate > Audacity to Generate > Built-in

Built-in is what we normally refer to them as in documentation e.g. this page in 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 this. Steve added his support by email

distinction between Open Project & Import audio file

Peter 05Mar17: Surely this is far more than a "wording" issue. It 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 Proposal. This old discussion could then be transferred to such a proposal's talk page.
  • Peter 07Mar17: My views on this:
    1. 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.
    2. 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)
    3. 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.
    4. 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.
    • 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.
      • Peter 24Mar17: Items 1 and 2 transferred to the Wording page - removed the P2



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:

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

  • 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 <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.

OpenImport.png


Old Discussions

playthrough

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

Peter 07Mar17: I moved this stale discussion to the "Old Discussions" section.

ToDo-2 It may even be better just to delete it.

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.

initial report by Ed Nov 2011 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).
  • 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):

Interactive.png

Here is the current progress dialog:
Ellipses.png
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..."
    ;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.

    Current discussion of possible visual standards are at:

    http://wiki.audacityteam.org/wiki/Visual_Consistency

  • 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":

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?