For background, making a form for users to add information about workshops was one of the formal usability testing tasks at UMN. Input formats was the only place the word appeared in Drupal, and a couple of people found their way there looking for places to input stuff.

This might have just been bad luck, but there's also some more compelling reasons to try to find an alternative.

1. Drupal doesn't filter user input. It filters on output. Input formats suggests that user input is going to be cleaned when it's submitted (which some systems do). This is misleading.
2. Although I think people can grok things like 'filtered HTML' quite easily, these are a level under the input formats fieldset/menu items. Something which introduces it better would help.
3. As Drupal has evolved, it's quite easy to have half a dozen filters in use in different configurations

We may also need to separate out the menu title for configuration from the legend for the fieldset as well so that admins and users get the information they need to.

Here's a few not very good ideas to get us started:

Output formats ;)
Filter groups (actually I quite like this one, but not on node/add)
Text filtering
Text formatting

Also, I think we should consider changing 'full HTML' to 'unfiltered HTML' to emphasise the security concerns more, this lines up with html escaping being it's own filter.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

dww’s picture

Yes, I've thought for a while that "input" was a misnomer here (and for the filters themselves). Really, the filters are "output filters", and the formats are ... err ... yeah, one of those things. ;) "Filter group" is accurate, but a little jargony. "Filter set" is more accurate and way more jargony, to the point that only CS people and mathematicians will understand. ;)

For the fieldgroup on node/add, "Text filtering" is probably the best choice. "Formatting" is going to invoke ideas of bold and italics, whereas "filtering" is going to invoke some idea of stripping out or converting things -- even if they don't fully get how output filtering works and all the security implications, I'd bet everyone's initial associations with the word "filter" at least get them headed in the right direction.

+1 to "unfiltered HTML", too.

Thanks for starting this issue, catch!

catch’s picture

OK, how's this for an initial run:

Change node/add fieldset and admin menu item from Input formats to Text filtering
Change individual input format to filter group
An individualfilter stays as filter.

That at least splits the three different things we're talking about, and although 'filter group' is a bit jargony, it does describe 'a group of filters', accurate jargon can be a good thing sometimes.

I may split off Full HTML/Unfiltered HTML to a different issue given it's probably a three line patch and can be done distinct from this one.

floretan’s picture

+1 for Text filtering, filter group and filter. There are 116 instances of "input format" in core, writing that patch will take some time. However, most of them are in comments or schema table documentation, so the update should be rather trivial.

For the filter names themselves Unfiltered HTML sounds good. However, if we use Text filtering instead of Input format, Filtered HTML will not indicate the purpose of the filter group, and could be confusing when co-existing with other filters (markdown, BBEdit, etc). Safe HTML is probably better. This can indeed be done in a separate patch, which I did at #245052: Rename input formats to reflect their purpose..

gaele’s picture

Over at http://drupal.org/node/48576#comment-621105 "Display filter(ing)" has been suggested for replacing "Input format".

I'm fine with #2 though (as long as we'll get rid of Input format ;-)

Sutharsan’s picture

Component: filter.module » usability

Moving all usability issues to Drupal - component usability.

ximo’s picture

I'd want to avoid the words input and output. The word format is also somewhat wrong, as it means "The layout of a document" according to Wiktionary.

Display filter was my suggestion, and it is more correct, yet it's one of those labels that can be misread as a verb.

I also like Text filter - it is right on point. It's the filter that the text goes through. Un point (+1) from me goes to Text filter.

+1 also goes to "Full HTML" --> "Unfiltered HTML", much better.

Rowanw’s picture

A few other ideas to throw around.

  1. Formatting options
  2. Formatting
  3. Text formatting
  4. Text filtering

I don't know what it is about 'ing' but it seems appropriate to me. :p

yoroy’s picture

What I don't like about 'filter' etc. is that it emphasizes what you can not do. It tells more about what we do to your text after you clicked the submit button.

Text format options?

gaele’s picture

@yoroy: this is exactly why I do like "filter". Drupal allows you to enter and submit anything you want. Filtering happens at display time, and removes anything that is not allowed. The current "input format" is confusing, and perhaps an example of too much "dumbing down".

sun’s picture

Throwing another fact into this discussion: Wysiwyg API ties client-side editors (aka. WYSIWYG editors) to input formats. By selecting an input format, a (different) editor may appear, or maybe none. I agree that "Input format" is a horrible term, but it also starts to make more sense, when different editors appear for different input formats... anyway, just wanted to note what's happening on the rich(-text) side of life currently.

Anonymous’s picture

Input format is definitely wrong and confusing. The filter is applied more to the rendering of the data and not to the actual input of the data and storage of the data. Format seems wrong as well since what we do is apply a filter to the text to remove or transform text so that the HTML engines do not do something ugly. So the option I like best is "Text filter" because it best describes the function; we are applying a filter to the text entered based on rules (options) set forth in the filter.

Full HTML should change to "No text filter" because it lets us know exactly what occurs.

sun’s picture

This is too limiting. An input format in Drupal defines and means:

  • The markup language being used, i.e. HTML, BBcode, Plain-text, etc
  • The allowed markup elements for the language, usable by the author of a post, i.e. tags or grammar to style a post.
  • Additional markup elements that are expanded into markup upon rendering of the output, such as inline macro tags, most often completely unrelated to the markup language, such as [inline|nid=123|title=Image].
  • The client-side editor associated to the input format (due to vast improvements of Wysiwyg API), which means: the user interface.
  • Internally: The markup elements, which are going to be stripped/removed from the rendered output.

Hence, an "input format" is a mixture of "language", "formatting", "embedding", "user interface" (GUI), and "output filtering".

Clearly, besides from the latter, the user chooses what she wants to communicate, and how she wants to communicate. Only the latter, i.e. the "real" input filters like "HTML filter" in core, are the opposite: Here, the site tells the user that if she wants to communicate, she must not/cannot use certain dialects.

ximo’s picture

I looked up the definitions of some suggested words...

Format (noun): The organization, plan, style, or type of something
Format (verb): To set the format of (input or output)
Formatting: The organization of information according to preset specifications (usually for computer processing)
Filter (noun): Device that removes something from whatever passes through it
Filter (verb): Remove by passing through a filter
Filtering: To pass through or as if through a filter

Technically speaking, an "input format" is a set of filters (the module is called filter.module). In additon to being able to remove "something", our filters can also format "something" (e.g. macros replacing [placeholders] with values, or adding a class to external links).

What bothers me is that we're really inconsistent in our terminology, using "input format" on node/add, while on admin/settings/filters we use both the terms "input format" and "filter format". What if we, before changing "Input format" on the node/add form, start by cleaning up the mess in the admin pages?

  • On admin/settings/filters, rename the page title from "Input format" to "Content filters"
  • On admin/settings/filters, rename all occurences of "input format" and "filter format" to "filter set" (e.g. "Add filter set")
  • Also, rename "Full HTML" to "Unfiltered HTML"?

Snapshots of how this would look:
admin/settings/filters
admin/settings/filters/add

sun’s picture

Current thoughts and discussion about adding "language information" to input formats: http://groups.drupal.org/node/15996

i.e. as mentioned in #12, "filter(s)" is too limited.

Rowanw’s picture

There's obviously no correct answer here and we'll never get a label that's both obvious and 100% accurate.

But I will argue that the word 'filter' may provoke negative connotations from the user. It's like asking someone if they would like to filter out the F word or the S word, take your pick. Why would you have someone choose how they'd like to be filtered, AKA restricted?

In the real Drupal world, input formats are commonly used as a way to choose a preferred markup language, such as HTML, Markdown or Textile (see groups.drupal.org). This is the real purpose of input formats in my opinion; to choose how you want to construct your content. Why else would there be a choice between formats?

I'm leaning strongly toward Text formatting. The reason being that when dealing with computers most people are aware of file formats such as HTML, TXT, PDF, etc... The definition of 'format' may say one thing, but the context it's used in can make all the difference (just look at all the various meanings throughout the answers.com page).

FWIW, Thunderbird uses Text formatting when referring to HTML and plain text. What do other common applications use?

Anonymous’s picture

@ximo: I agree with your observation of the inconsistencies.

On the content filters->list I think the "All roles may use default format" should become "All roles have been selected to use this filter set" and "No roles may use this format" should become "No roles have been selected to use this filter set".

As for the topic of "Input format" I agree that to an end user the filter is too technical and could seem limiting. I am fine with "Text formatting" to describe the applicable use of a filter set.

gaele’s picture

So, to summarize, a Drupal input format is not an input format (because it formats output) and a Drupal filter is not a filter (because it may transform instead of remove). Hmm ;-)

SteveBayerIN’s picture

Is calling it 'Allowed tags' or 'Allowed markup code' over simplifying it?

I'd prefer to see the widget/form field for node entry to have 'Allowed Markup Code' while the site configuration for the same titled as 'Markup Parser,' 'Markup Parsing' or 'MarkUp Processor' (whichever may apply.)

catch’s picture

Since not all formats involve actual filtering (i.e. the PHP format), I'd be really happy if we could settle on 'Text formatting' - which appears to be the preferred option. It's extra handy if Thunderbird uses it too.

So we can change the main menu item, 'Input formats' to 'Text formatting'.

This still leaves the question of what to do with individual input formats and filters.

So our main heading for the admin menu, and for the 'input format' field on content creation becomes: Text formatting([ideally this should be the only heading that content creators ever see)

An individual input format? Filter group - Text format - Filter set?

An individual filter?
[I still think we can get away with leaving this as it is, and would vote for having 'filter group' or 'filter set' to describe more than one of these acting together).

keith.smith’s picture

I like filter set. To me, at least, it applies a collection of things applied in a specific order.

Anonymous’s picture

And no filters is still a valid filter set. I prefer Filter set since this comes from the filter routines.

bsherwood’s picture

While possibly incorrect, I personally think most non-Drupal users would understand "Text Formatting".

There needs to be a separation between drupal admin's and their sites visitors/users. While most of us (Drupal dev's and admin's) have some level of technical savvy, a lot of users do not and we need to follow the KISS principle. Even though it may be incorrect by dictionary definitions, an "easier" name will resonate better with the average user.

Personally I think 'input format' is incorrect as well, since it formats output and doesn't format input at all.

sun’s picture

In general, I agree with specmav. As long as we do not separate out markup language, input "features", and output filters, choosing a term that is technically correct for Drupalers will hurt anyone else, so

+1 for Text formatting

However, we only have "input format" and "filter" currently, so there is no need for introducing a new layer and term of "filter sets", which apparently does not exist.

To recap and enhance ximo's list:

  • Rename admin/settings/filters to admin/settings/filter (Module name like anywhere else)
  • On admin/settings/filters, rename the menu/page title from "Input formats" to "Text formattings"
  • On admin/settings/filters and sub-pages, rename all occurences of "input format" and "filter format" to "text formatting" (e.g. "Add text formatting")
  • "All roles may use default format" becomes "All roles may use the default text formatting"
  • "No roles may use this format" becomes "No roles may use this text formatting"
  • In forms, rename "Input format" to "Text formatting"
  • Also, rename "Full HTML" to "Unsafe HTML" - it should be 100% clear to all users that this format should only be used by privileged users.
dww’s picture

As a native English speaker, I find "Text formattings" confusing. It's not a real word, either. I don't see what "ing" buys anyone in readability or clarity here. If we're going with "Text formatting" (woe to the users who think this only means bold/underline, which I assert is a fairly common understanding of what "text format" means), we should just use "Text format(s)?", instead. So, here's an alternate complete list, this time with Real English Words(tm). ;)

  • Rename admin/settings/filters to admin/settings/filter (Module name like anywhere else)
  • On admin/settings/filters, rename the menu/page title from "Input formats" to "Text formats"
  • On admin/settings/filters and sub-pages, rename all occurences of "input format" and "filter format" to "text format" (e.g. "Add text format")
  • "All roles may use default format" becomes "All roles may use the default text format"
  • "No roles may use this format" becomes "No roles may use this text format"
  • In forms, rename "Input format" to "Text format"
  • Also, rename "Full HTML" to "Unsafe HTML" - it should be 100% clear to all users that this format should only be used by privileged users.

I'm still not thrilled about "format", but given that the "filter sets" are composed of individual filters, calling the sets "text filters" is even worse. So, given the lack of a better alternative, I'm hereby in favor of the list I just outlined.

keith.smith’s picture

"Text formats" is ok. I also like it better than "Text formattings". Note that we also need to add adjusting help text pages for admin/help/filter (and possibly others) to the list.

catch’s picture

Renaming Full HTML and Filter HTML is over at #245052: Rename input formats to reflect their purpose. so we should keep that change there. Otherwise I'm happy enough with sun's/dww's list - although are we happy that 'a text format' might include multiple formats - i.e. HTML and BBCODE could be supported in one 'format' that was the motivation for using 'filter set' in the first place.

sun’s picture

gngn... for DX and consistency, #input_format would have to become #text_format, too.

To be honest, I also thought about cutting it down to "Text format" when writing #23. I'm fine with that, although I'm concerned about the "text" in it, since it refers to a language (actually, it's either plain-text, HTML, BBcode, PHP, ...), and might not be translatable into other languages ("Input format" is a pain in this regard, too).

So, albeit dww's point about wrong assumptions, why not cut it down even further to "Formatting" (which ximo outlined in #13 already, but was not considered further yet).

# /Text format/Formatting/gi < #24

keith.smith’s picture

Status: Active » Needs review
FileSize
48.01 KB

Here's a down payment on this patch. I'm sure it's not yet complete, but I have adjusted occurrences of "Input format(s)" to "Text format(s)". admin/settings/filters has been renamed to admin/settings/filter, and various help texts have been updated.

Note that in this patch, a "text format" still contains various filters, each filter responsible for a specific formatting task. Where the UI referred to filters in this sense, I hope I left them alone.

I did not change any of the variable names in the code. I did try to adjust code comments.

I did not rename Full HTML since that is covered by the issue referenced in #26.

Even though this may not be complete, I'm setting it to CNR to see what the test bot thinks. The filter tests pass on my system.

Dries’s picture

I'm OK with this patch, but I'd really like to see us rename the variables at the same time. This might be reasonable easy with some global search and replace fu. If it is too much work for one patch, I'm OK with deferring the second part.

Status: Needs review » Needs work

The last submitted patch failed testing.

edmund.kwok’s picture

Component: usability » base system
Status: Needs work » Needs review
FileSize
43.61 KB

Rerolled keith.smith's patch and also renamed the #input_format property to #text_format. Are there other variables that are supposed to be renamed?

Anonymous’s picture

Issue tags: +Usability

I don't like the term "text format" any better than I like "input format"; yes I reread the history and know what was agreed to. What we really have is a rule set of filters for the node and would prefer to call it "node filter set", "node filters" or "node text filters" for that reason. "Text format" sounds like a description of how the text is formatted in the text box rather than a set of filters. "Input format" sounds like a description of how the input is formatted when entered.

catch’s picture

input formats don't only apply to nodes - they apply to blocks and many other textareas, so that's not an option.

yoroy’s picture

Noticed how the usability peoples have been avoiding this issue? :-) This is the stuff you can argue about indefinitely. Wording issues can only be resolved through user testing. (And striving towards the most "correctness" isn't always helpful, it's better to look for the words that users come up with themselves when looking for something)

That said, changing 'input format' to 'text format' is at least making things less abstract, more specific while using a simpler word. So I expect this to perform better.

Dries’s picture

Status: Needs review » Needs work
Issue tags: -Needs usability review, -Needs text review

Committed to CVS HEAD. Please update the documentation (i.e. upgrade instructions) and mark as 'fixed' after.

sun’s picture

Status: Needs work » Needs review
Issue tags: +Needs usability review, +Needs text review

I reviewed the patch and it looks very solid and clean. It looks like a different issue has been mixed into the patch though (rename path admin/settings/filters to admin/settings/filter). However, I would be OK with committing that change in this issue.

Since the test bot seems to be happy, we just need some manual tests of the changes (since this is a usability issue) - which I did not do yet.

sun’s picture

Status: Needs review » Needs work
Issue tags: -Needs usability review, -Usability, -Needs text review +Needs documentation

WOW. Dries beat me to it 8)

Reverting status.

Xano’s picture

FileSize
3.48 KB

At some points 'filter format' was still being used. The attached patch converts these occurrences to 'text format'. Also, we should think of renaming {filter_format} to {text_format}.

keith.smith’s picture

Oops. I thought I had gotten them all. Thanks, Xano!

One comment unrelated to this patch other than you're changing the string anyway:

+      form_set_error('name', t('Text format names need to be unique. A format named %name already exists.', array('%name' => $name)));

Can we make this:

+      form_set_error('name', t('Text format names must be unique. A format named %name already exists.', array('%name' => $name)));
Xano’s picture

#input_format needs to be updated to #text_format.

David_Rothstein’s picture

Status: Needs work » Needs review
FileSize
13.35 KB

I came across some other places that had not been properly converted... so I updated @Xano's patch to include them as well. This also includes the rewording suggested by Keith Smith above.

spade’s picture

I am glad this is being worked on, because this misnomed got me confused lately. Subscribing to this issue. FSp.

xmacinfo’s picture

Input format renaming affects #304330: Text format widget. Might be good to prioritise which one to do first.

Dave Reid’s picture

@xmacinfo This issue should be fixed first, because it actually has been committed to core, but juts a few spare fixes are needed for consistence.

xmacinfo’s picture

Status: Needs review » Reviewed & tested by the community

I've applied this patch again a clean Drupal Head and don't see any issue.

This patch is most welcome since it standardise the naming and labeling. Like comment #43 says, there will be less confusion. And Dave says we should commit this patch before #304330: Text format widget. So I guess it's commit time. :-)

Dries’s picture

Status: Reviewed & tested by the community » Fixed

Committed to CVS HEAD. Thanks!

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.

David_Rothstein’s picture

Status: Closed (fixed) » Needs work

Seems like this should still be at "needs work" as per Dries's comments in #35 (upgrade documentation changes).

David_Rothstein’s picture

Status: Needs work » Needs review

OK, looking through the patches that were committed, I made the only changes to the update documentation that seemed necessary:

I did not add a specific section to talk about the "input format" => "text format" terminology change itself (didn't seem worth it), nor did I add anything about the CSS class changes from the latest patch, i.e. "input-format-order" => "text-format-order" and "input-format-order-weight" => "text-format-order-weight" (didn't seem totally necessary, but maybe it is).

Status: Needs review » Needs work

The last submitted patch failed testing.

David_Rothstein’s picture

Status: Needs work » Active

Uh, duh :) This is why Drupal needs new issue statuses....

Leaving at "active" until someone can confirm that all the required changes to the upgrade documentation have now been made.

dww’s picture

"This is why Drupal needs new issue statuses...."

No, the test bot just needs to not be so stupid. ;)

catch’s picture

Status: Active » Fixed

Docs changes look fine, only issue I could think of is if someone's tracking unstables and has to go back for the text format changes, but repeating the same thing twice would be worse.

Status: Fixed » Closed (fixed)
Issue tags: -Needs documentation

Automatically closed -- issue fixed for 2 weeks with no activity.