Use "method" instead of "variable" for methods

[jmooring]

Recently, I spent a significant amount of time attempting to define the "language of Hugo" while creating a glossary of terms. This was a challenging exercise, as I had to reconcile current usage with terms that are specific and (mostly) narrowly defined. This is comparable to, but much less time-consuming than, writing the Go language specification ten years after the language was first released.

Although our language choices have, for the most part, been logical and consistent, I think it's time to use the term "method" instead of "variable", with the exception of variables initialized within template actions (e.g., {{ $myVar := 42 }}).

Justification:

1. Things like "page variables" are not variable. They are immutable within a template.
2. Our current usage is confusing. We call .Page.Title and .Page.IsSection variables, but we call .Page.RenderString a method.
3. This would cleanup the "Functions" section. Although we call .Page.RenderString a method, we document it under the "Functions" section.

We've already done this for .Pages. Although under the "Variables" section, the title is "Pages methods".

Tasks

Completed on or before 4 Nov 2023:

• Namespace all functions (effort: medium)
• Create Methods section (effort: low)
• Move methods (anything that begins with a dot) from Functions to Methods (effort: low)
• Add and namespace methods on Page, Site, etc. (effort: high)
• Create quick reference guides for functions and methods (effort: medium)
• Add notice to all Variables pages, pointing readers to the Methods quick reference guide and the Methods section

Completed on 19 Feb 2024:

• Remove Variables section after a few months

Completed on 8 Mar 2024:

• Rework the introduction to templating

Remaining tasks:

• Ensure consistent use of "function", "method", and "variable" throughout the documentation (effort: medium)
• Use "argument" instead of "parameter" when referring to function, method, and shortcode arguments

I've been thinking about doing this for a while: #1639

[bep]

So, it's still very much on my TODO list to get an auto generated reference section happening in Hugo. The recent config consolidation was a important part of this, and then I may have gotten distracted.

With that setup you would get this "Reference":

• Function namespaces
• Objects (Page, Site etc.)
• Configuration
• Go Types

While it's technically correct to say that Hugo's template functions are methods, they (mostly) behave like a function, and none of them have a "." context that the user needs to worry about, and I think the distinction between function and method is something that we need to preserve.

So with that, I would not spend high amount of effort on things that would fall into the "Reference" category above.

[jmooring]

I think the distinction between function and method is something that we need to preserve

I agree, and that is consistent with the glossary of terms.

What I am asking is, can we stop referring to things like .Page.IsHome and .Page.Title as variables, and call them methods instead?

[chrillek]

1. Things like "page variables" are not variable. They are immutable within a template.

Why not call them "properties"? That doesn't imply mutability (I think), but still permits to discern those from functions like RenderString.

[jmooring]

They are not properties. They are methods. For example:

1. .RenderString is not a function. It is a method on the .Page object that renders markdown to HTML.
2. .Title is a method on the .Page object that returns the front matter title field
3. .Sections is a method on the .Site object that returns a collection of all the top level sections.

[chrillek]

Well, if they are methods… I doubt that kind of terminology helps clarify things, though. A getter like .Title behaves in every way as a read-only property. Whereas .RenderString acts on its parameter(s).

If you replace (most) "variable" by "method" the intro to Site variables will read:

Site methods
Many, but not all, site-wide variables are defined in your site’s configuration. However, Hugo provides a number of built-in methods for convenient access to global values in your templates.
The following is a list of site-level (aka “global”) methods. Many of these methods are defined in your site’s configuration file, whereas others are built into Hugo’s core for convenient usage in your templates.

I do not think that that makes any sense, at all. The current wording is a lot less complex and easier to understand. Even if it might not be technically correct.