User-replaced values format is inconsistent with IBM's style guide and technically incorrect

[mnsteven]

I have recently become aware that our supplementary style guide notes that user-replaced values in format and code should be enclosed in angle brackets and italicized, both. I ask the team to reconsider this, as it is idiosyncratic, inconsistent with IBM's style guide, and -- in the case of code examples -- simply wrong in a technical sense as it implies that the angle brackets are literals.

This is the section in question:

https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values

As history, the convention of angle brackets to indicate a variable in a syntax statement comes from a time when only monospaced fonts were available. This is an example of a man page in this older style (in the main format statement -- but if you look through the man page you find examples of both angle brackets and italic font and in one case both, just to confuse things, but the main format statement shows the old style):

https://man7.org/linux/man-pages/man1/abicompat.1.html

Once italic fonts became more generally available for man page display, italic became the standard as it had always been for expressing variables in mathematical statements. This is an example of a more modern man page that uses this convention:

https://manpages.org/a2dismod/8

These are the two formats I had previously been aware of. It turns out that the angle bracket plus italic convention does sometimes carry over, as in this man page, but that seems to be rare:

https://manpages.org/accessdb/8

The IBM style guide notes italic as the font to use for command syntax, with the exception of times when you think the command syntax will be copied to a format that does not support italics This is consistent with the standard that angle brackets are used only when italic is not available. This not what the Red Hat supplementary guide says, which is that we should always use both italics and angle brackets, not just in this edge case.

https://www.ibm.com/docs/en/ibm-style?topic=elements-command-syntax

Other sections of the IBM style guides are far more direct in noting the use of italics (with no mention of angle brackets):

https://www.ibm.com/docs/en/flashsystem-v7000u/1.5.2?topic=commands-command-syntax-conventions

Those examples are limited to command syntax, where angle brackets plus italics are not necessary but will likely be understood by people familiar with the older monospaced style (not something I think you can rely on any longer), but our style guide goes further and notes that variables in code blocks should also be in italic font and enclosed with angle brackets, which is where I think it's technically incorrect.

As a start, I think it's a bad idea to include user-replaced values in an actual code example. The example should be an example, not a syntax statement. It's not always clear what a variable means (target? path-to-x?) and an actual example usually clarifies that. As a style point, the user-replaced values can be noted in the text introducing the code example ("The following command sets a password of mypassword"). But if it seems necessary to include a user-replaced variable in a code block, the italic font would indicate this and anything not in italics is a literal. Even if you mark angle brackets as italic, they do not appear as italic in the document, at least not that I can discern. This would mean that you would literally enter those angle brackets in the code, surrounding your value for the user-replaced variable. I think people are familiar enough with the angle bracket convention that this will not likely be a problem, but it is still wrong.

In any case, my understanding is that the IBM style guide takes precedence over our supplementary guide, and the IBM style guide does not require both angle brackets and italic font.

Steven Levine slevine@redhat.com

[mportman12]

@mnsteven I think this is a much larger discussion for the group, but one quick note: Supplementary Style Guide takes precedence over IBM Style Guide - in fact, the SSG mostly contains style guidelines that differ from ISG.

[bergerhoffer]

Hi @mnsteven - Miriam is correct, the SSG takes precedence over the ISG and only includes things that are not covered by the ISG, or differ from the guidance in the ISG.

See this section in the SSG that clarifies this: https://redhat-documentation.github.io/supplementary-style-guide/#_how_to_use_this_guide

The replaceable value format that you see recommended in the SSG was a result of a very long discussion, and included input from all of CCS via a survey where we had over 80 responses. The overwhelming majority of responders were in favor of including angle brackets in the replaceable value format. And all other aspects of the format were the majority too (underscores, italics, lowercase).

Because this is an issue that was discussed and evaluated in great depth in 2020, I don't think that it's something we'll want to change.

[mnsteven]

I'm curious what the arguments were for including literals in a code block that are not actually part of the code.

There are times when angle brackets are actual operators (greater than, less than) -- how do you distinguish?

If sumtotal < <_partfotal_> and <_parttotal_> > semitotal...

That might even be written like this, which is not something I would want to see:

If sumtotal<<_partfotal_> and <_parttotal_>>semitotal...

The >> and << sequences have specific meanings in code (they are "bitwise shift operators").

[bergerhoffer]

IMO users would need to take the context into consideration. In places where angle brackets are used as actual operators, I would think that the spacing would be important (as in, it should be written as your first example, and not your second).

Also, the addition of italics is another important piece that distinguishes the literal angle bracket from an angle bracket that is part of a replaceable value.

[mnsteven]

In most cases, it is perfectly legal code to include no spaces around an operator. There are coding style guidelines a programmer follows, but is it the function of our style board to set those?

An italicized angle bracket is indistinguishable from a non-italicized angle bracket. I have prepared a document with three examples that show what I think the problem is here. These are actual examples from our documentation.

https://docs.google.com/document/d/1e4WxfUEvn1_J1dI2TfWHv2EhvVTXKv4__PBWf8OfGYI/edit

In that first example, if any of the items were variables, it would be technically wrong to add a space before or after an angle bracket. The code would not parse.

The second example is a similar one where the issue may be more pronounced.

The third example shows what the second example would look like if "service" were a variable, according to our style. Those angle brackets surrounding "service" are italicized and are not distinguishable from the surrounding delimiters, and in this context they would pretty certainly be interpreted as literals (especially since our style of both italics and angle brackets is non-standard) . This code example is incorrect if we follow our style

[bergerhoffer]

This was discussed at the 29 June SSG meeting. Since the replaceable value issue was researched and discussed at great length when it was added to the SSG, we agreed that this isn't something that we should revisit unless there is customer confusion or a true need. Closing this issue.

[mnsteven]

When you say that this was discussed at that meeting, do you mean people actually looked at example 3 in my attachment and decided that was ok, or that the discussion was just "we will not revisit this"? From what I can tell, the initial discussion was about a replacement value in a format statement, but not within a code example itself. Those are separate issues.

[bergerhoffer]

@mnsteven I can't speak to how many people actually looked at your examples, but primarily the discussion was mostly that we won't revisit this. The replacement values should work in a code example as well.

We did awhile ago realize that the existing guidance didn't work for XML though, which is what your latest examples look like. I'm not sure if you've seen it or not, but we have different guidance for replaceable values in XML, since we realized that the normal bracketed format didn't work. https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values-xml

If you haven't seen that section yet, please take a look, hopefully that helps with your XML examples.