The value of format tags

Status
Not open for further replies.

wblock@

Developer
These forums use format tags like [FILE], [CMD], [CODE], and [PORT] extensively.

It is not because we are just sticklers for detail (well, okay, that too), but also because these tags make the messages easier to read and add useful extra information for the reader. For example:

Without tags:
Set 'sshd_enable="YES"' in /etc/rc.conf.​
With tags:
Set sshd_enable="YES" in /etc/rc.conf.​

The first version uses quote marks to mark the special text. But that is not clear to all users, and they often can't tell whether the quotes are part of a string or command.
The second version uses tags to mark the special text. The user can clearly see which parts are special, and there are no extra quote marks to cause confusion. (The [FILE] tag is used to highlight the variable here. Even though it is not a filename, we use this tag to highlight inline special text.)

Another example without tags:
See Xorg(1) for more information. This is only present after the x11/xorg port or package has been installed.​
With tags:
See Xorg(1) for more information. This is only present after the x11/xorg port or package has been installed.​

In the second version, the [MAN] and [PORT] tags make links out of the man page and the port name. The user does not need to open another window to read that man page, and clicking the port link takes them directly to that port's page on Freshports.

Another example without tags:
Use "sed -e 's/abc/123/g' filename" to replace all the "abc" strings with "123".​
With tags:
Use sed -e 's/abc/123/g' filename to replace all the abc strings with 123.​

The command is clearly visible and there is no question of which quote marks the reader is actually supposed to enter.

In summary, we really like it when people use tags because it makes the message clearer and gives added information to the reader. If you find yourself typing quote marks, it often means that a tag should be used instead.

A short list of tags with examples can be seen here.

Thank you!
 
Last edited by a moderator:
Status
Not open for further replies.
Back
Top