docs: add example of passing in account param

[jondkinney]

I had to read the source to figure out how to pass in the account param.

[halostatue]

I’m not sure that this example is necessary, but collapsing the examples might be better, like is done with onepasswordDetailsFields. There's nothing strictly wrong with the example, though.

The top line of the file (onepasswordRead.md:1) shows that the second optional parameter is the account, which is the pattern for all template functions.

[twpayne]

The optional account parameter is shown at the top of the page and described in the text, so I don't think this example is necessary.

[jondkinney]

Is it obvious to people though that the way to pass that second parameter in is with a space separated second quoted string?

I saw that [account] was the second optional parameter, but getting the formatting correct to test it at the command line with execute-template took me nearly a dozen attempts, and ultimately sending the source to ChatGPT to ask it how it should be formatted. The lack of argument separators is not something that I'm overly familiar with nor does it seem particularly obvious when reading line 1 at the top of the page. Do you expect all the users of your library to already be familiar with Go?

[halostatue]

Is it obvious to people though that the way to pass that second parameter in is with a space separated second quoted string?

Mostly yes, because it's in a reference to a templating function. This specific function only has the single example, but in the same section, there are other examples that show how multiple parameters are used, as with onepassword.

I saw that [account] was the second optional parameter, but getting the formatting correct to test it at the command line with execute-template took me nearly a dozen attempts, and ultimately sending the source to ChatGPT to ask it how it should be formatted. The lack of argument separators is not something that I'm overly familiar with nor does it seem particularly obvious when reading line 1 at the top of the page. Do you expect all the users of your library to already be familiar with Go?

With Go, no. But the second paragraph of templating points to Go's text/template reference. text/template is similar to Liquid and Jinja templating languages in that it operates on pipelines and function parameters are positional with whitespace separation (and quotes to pass parameters with spaces in them).

I hope that this distinction helps understand the reasoning. This isn't to say that improvements can't be made, but it is fair to expect some exploration and review the examples provided, not just for the single command being looked up, but other related commands.

[jondkinney]

@twpayne I think the suggestion of collapsing the examples like @halostatue suggested to match the style of the other entries would be very helpful. Every other doc page in the 1Password section has examples of how to use the template function with each of the optional parameters with the notable exceptions of the onepasswordItemFields and onepasswordRead functions.

If that example were there for the onepasswordRead function, it would have helped me tremendously.