Markup in cache notes

httplint/field/parsers/cache_control.py

@@ -9,7 +9,7 @@
 from httplint.field.utils import unquote_string
 
 
-# known Cache-Control directives; assumed to not allow duplicates
+# known cache directives; assumed to not allow duplicates
 # values are (valid_in_requests, valid_in_responses, value_type)
 KNOWN_CC: Dict[str, Tuple[bool, bool, Union[None, Callable]]] = {
     "immutable": (False, True, None),
@@ -32,7 +32,7 @@
     "post-check": (False, True, int),
 }
 
-# Cache-Control directives and those they override. Listed in order of
+# cache directives and those they override. Listed in order of
 # significance; only the first match will be shown.
 CONFLICTING_CC: List[Tuple[str, List[str]]] = [
     (
@@ -133,7 +133,7 @@ def evaluate(self, add_note: AddNoteMethodType) -> None:
                         add_note(
                             CC_CONFLICTING,
                             directive=directive,
-                            conflicts=prose_list(conflicts),
+                            conflicts=prose_list(conflicts, markup="`"),
                         )
                         break  # only show the first conflict
 
@@ -192,37 +192,37 @@ def evaluate(self, add_note: AddNoteMethodType) -> None:
 class BAD_CC_SYNTAX(Note):
     category = categories.CACHING
     level = levels.BAD
-    _summary = "The %(bad_directive)s Cache-Control directive's syntax is incorrect."
+    _summary = "The %(bad_directive)s cache directive's syntax is incorrect."
     _text = "This value must be an integer."
 
 
 class CC_MISCAP(Note):
     category = categories.CACHING
     level = levels.WARN
-    _summary = "The %(directive)s Cache-Control directive has non-lowercase characters."
+    _summary = "The %(directive)s cache directive has non-lowercase characters."
     _text = """\
-Cache-Control directive names are case-insensitive, but some implementations don't
+cache directive names are case-insensitive, but some implementations don't
 recognize directives that aren't all-lowercase.
 
-Therefore, it's safest to use %(directive_lower)s instead of %(directive)s."""
+Therefore, it's safest to use `%(directive_lower)s` instead of `%(directive)s`."""
 
 
 class CC_DUP(Note):
     category = categories.CACHING
     level = levels.WARN
-    _summary = "The %(directive)s Cache-Control directive appears more than once."
+    _summary = "The %(directive)s cache directive appears more than once."
     _text = """\
-The %(directive)s Cache-Control directive is only defined to appear once; it is used more than
+The `%(directive)s` cache directive is only defined to appear once; it is used more than
 once here, so implementations may use different instances (e.g., the first, or the last),
 making their behaviour unpredictable."""
 
 
 class CC_CONFLICTING(Note):
     category = categories.CACHING
     level = levels.WARN
-    _summary = "The %(directive)s Cache-Control directive overrides other directives."
+    _summary = "The %(directive)s cache directive overrides other directives."
     _text = """\
-The %(directive)s Cache-Control directive overrides or conflicts with %(conflicts)s.
+The `%(directive)s` cache directive overrides or conflicts with %(conflicts)s.
 
 The conflicting directives will be ignored by caches, and can be safely omitted.
     """
@@ -232,18 +232,18 @@ class CC_WRONG_MESSAGE(Note):
     category = categories.CACHING
     level = levels.WARN
     _summary = (
-        "The %(directive)s Cache-Control directive has no meaning in a %(message)s."
+        "The %(directive)s cache directive has no meaning in a %(message)s."
     )
     _text = """\
-The %(directive)s Cache-Control directive is only defined to appear in %(other_message)s
+The `%(directive)s` cache directive is only defined to appear in %(other_message)s
 messages; is has no defined meaning in a %(message)s."""
 
 
 class CHECK_SINGLE(Note):
     category = categories.CACHING
     level = levels.WARN
     _summary = (
-        "Only one of the pre-check and post-check Cache-Control directives is present."
+        "Only one of the pre-check and post-check cache directives is present."
     )
     _text = """\
 Microsoft Internet Explorer implements two `Cache-Control` extensions, `pre-check` and
@@ -259,7 +259,7 @@ class CHECK_SINGLE(Note):
 class CHECK_ALL_ZERO(Note):
     category = categories.CACHING
     level = levels.WARN
-    _summary = "The pre-check and post-check Cache-Control directives are both '0'."
+    _summary = "The pre-check and post-check cache directives are both '0'."
     _text = """\
 Microsoft Internet Explorer implements two `Cache-Control` extensions, `pre-check` and
 `post-check`, to give more control over how its cache stores responses.
@@ -277,7 +277,7 @@ class CHECK_POST_BIGGER(Note):
     category = categories.CACHING
     level = levels.WARN
     _summary = (
-        "The post-check Cache-control directive's value is larger than pre-check's."
+        "The post-check cache directive's value is larger than pre-check's."
     )
     _text = """\
 Microsoft Internet Explorer implements two `Cache-Control` extensions, `pre-check` and
@@ -292,7 +292,7 @@ class CHECK_POST_BIGGER(Note):
 class CHECK_POST_ZERO(Note):
     category = categories.CACHING
     level = levels.BAD
-    _summary = "The post-check Cache-control directive's value is '0'."
+    _summary = "The post-check cache directive's value is '0'."
     _text = """\
 Microsoft Internet Explorer implements two `Cache-Control` extensions, `pre-check` and
 `post-check`, to give more control over how its cache stores responses.

httplint/util.py

@@ -53,18 +53,19 @@ def display_bytes(inbytes: bytes, encoding: str = "utf-8", truncate: int = 40) -
     return "".join(out)
 
 
-def prose_list(inlist: List[str]) -> str:
+def prose_list(inlist: List[str], markup:str = "") -> str:
     """
     Format a list of strings into prose.
     """
     length = len(inlist)
+    m = markup
     if length == 0:
         return "(none)"
     if length == 1:
-        return inlist[0]
+        return f"{m}{inlist[0]}{m}"
     if length == 2:
-        return f"{inlist[0]} and {inlist[1]}"
-    return f"{', '.join(inlist[:-1])}, and {inlist[-1]}"
+        return f"{m}{inlist[0]}{m} and {m}{inlist[1]}{m}"
+    return f"{', '.join([f'{m}{i}{m}' for i in inlist[:-1]])}, and {m}{inlist[-1]}{m}"
 
 
 def relative_time(utime: float, now: float = None, show_sign: int = 1) -> str: