Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Require italics to explain abbreviations #990

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Require italics to explain abbreviations #990

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/sources/review/lint-prose/rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
date: "2024-06-25"
description: A description of every Grafana Labs prose linting rule.
menuTitle: Rules
review_date: "2025-01-16"
review_date: "2025-01-22"
title: Vale rules
---

Expand Down Expand Up @@ -1083,7 +1083,7 @@ The following rules are suggestions to consider a certain point of style.

Extends: conditional

Spell out _`<CURRENT TEXT>`_, if it's unfamiliar to the audience.
Spell out _`<CURRENT TEXT>`_, if it's unfamiliar to the audience. To spell out the abbreviation, you must enclose the full spelling and the abbreviation in parentheses, with italic emphasis. For example, _application programming interface (API)_.

[More information ->](https://developers.google.com/style/abbreviations)

Expand Down
5 changes: 3 additions & 2 deletions vale/Acronyms.jsonnet
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
local defs = (import './dictionary.libsonnet').words;
std.manifestYamlDoc({
extends: 'conditional',
message: "Spell out '%s', if it's unfamiliar to the audience.",
message: "Spell out '%s', if it's unfamiliar to the audience. To spell out the abbreviation, you must enclose the full spelling and the abbreviation in parentheses, with italic emphasis. For example, _application programming interface (API)_.",
link: 'https://developers.google.com/style/abbreviations',
level: 'suggestion',
ignorecase: false,
// Ensures that the existence of 'first' implies the existence of 'second'.
first: '\\b([A-Z]{3,5})\\b',
second: '(?:\\b[A-Z][a-z]+ )+\\(([A-Z]{3,5})\\)',
second: '_(?:[A-Za-z][a-z]+ )+\\(([A-Z]{3,5})\\)_',
scope: 'raw',
// ... with the exception of these:
exceptions: [
'%s' % def.word
Expand Down
5 changes: 3 additions & 2 deletions vale/Grafana/styles/Grafana/Acronyms.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,5 +75,6 @@
"ignorecase": false
"level": "suggestion"
"link": "https://developers.google.com/style/abbreviations"
"message": "Spell out '%s', if it's unfamiliar to the audience."
"second": "(?:\\b[A-Z][a-z]+ )+\\(([A-Z]{3,5})\\)"
"message": "Spell out '%s', if it's unfamiliar to the audience. To spell out the abbreviation, you must enclose the full spelling and the abbreviation in parentheses, with italic emphasis. For example, _application programming interface (API)_."
"scope": "raw"
"second": "_(?:[A-Za-z][a-z]+ )+\\(([A-Z]{3,5})\\)_"
2 changes: 1 addition & 1 deletion vale/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ STYLES := Grafana/styles/Grafana/Google Grafana/styles/Grafana/Readability
RULES := Grafana/styles/Grafana/Acronyms.yml Grafana/styles/Grafana/AmazonProductNames.yml Grafana/styles/Grafana/ApacheProjectNames.yml Grafana/styles/Grafana/GoogleProductNames.yml Grafana/styles/Grafana/Headings.yml Grafana/styles/Grafana/ProductPossessives.yml Grafana/styles/Grafana/WordList.yml
DOCUMENTATION := ../docs/sources/review/lint-prose/rules.md

all: $(DICTIONARIES) $(DOCUMENTATION) $(RULES) $(STYLES) $(TESTS) ## Build all the Grafana Vale rules and styles.
all: $(DICTIONARIES) $(DOCUMENTATION) $(RULES) $(STYLES) ## Build all the Grafana Vale rules and styles.
$(DOCUMENTATION): $(wildcard Grafana/styles/Grafana/*) $(wildcard ../tools/cmd/generate-documentation/*)
cd ../tools/ && go run ./cmd/generate-documentation ../ tools/cmd/generate-documentation vale/Grafana/styles/Grafana docs/sources/review/lint-prose/rules.md
prettier -w $(DOCUMENTATION)
Expand Down
Loading