Help people to know when an example is literal

I'm writing to suggest a change in the documentation for: views-view-field.tpl.php

<?php
// $Id: views-view-field.tpl.php,v 1.1 2008/05/16 22:22:32 merlinofchaos Exp $
 /**
  * This template is used to print a single field in a view. It is not
  * actually used in default Views, as this is registered as a theme
  * function which has better performance. For single overrides, the
  * template is perfectly okay.
  *
  * Variables available:
  * - $view: The view object
  * - $field: The field handler object that can process the input
  * - $row: The raw SQL result that can be used
  * - $output: The processed output that will normally be used.
  *
  * When fetching output from the $row, this construct should be used:
  * $data = $row->{$field->field_alias}
  *
  * The above will guarantee that you'll always get the correct data,
  * regardless of any changes in the aliasing that might happen if
  * the view is modified.
  */
?>
<?php print $output; ?>

I would be totally embarrassed to tell you how many hours I spent fiddling with: $data = $row->{$field->field_alias} (8 rows from the bottom).

It turns out that that code example is meant to be taken 100% literally. You copy and paste it... you don't replace "field_alias" with the field alias, field name, field ID or anything else. In retrospect, I think the curly brackets may have been the clue that no replacements were needed inside them. However, that is just not obvious for anyone but advanced Views users.

Since there isn't a good notation system in providing code examples to tell the coder when something is literal and when it should be replaced with data specific to the code they are writing... I think we have to get verbose in the description.

In this case, the word "construct" is a bad choice in my opinion. A "construct" suggests that example being presented is a modal of something that needs adapting for your situation. "Construct" connotes "general" not "particular."

I propose this: "When fetching output from the $row, use the following snippet. No replacements are needed; use the snippet without editing:"

The problem I'm pointing out is obviously not unique to views-view-field.tpl.php; it's probably the biggest problem out there in the world of documentation. I think my suggestion would make an improvement for this one tiny part of the problem.

best,

Shai Gluskin