search

errata-ai / Microsoft

A Vale-compatible implementation of the Microsoft Writing Style Guide.
https://github.com/errata-ai/vale
MIT License
84 stars 46 forks source link

Headings.yaml seems to flag any heading that contains punctuation #18

Closed felicitymay closed 5 years ago

felicitymay commented 5 years ago

I'm setting up Vale to run some of these Microsoft rules as an automated Jenkins test for our Sphinx documentation and it's mostly working beautifully. I'm a little puzzled by the output for some of the headings. For example:

Top-level entities
------------------

Modules include five kinds of top-level entity: predicates, classes, modules, aliases, and select clauses.

Non-member Predicates
~~~~~~~~~~~~~~~~~~~~~

A *predicate* is declared as a sequence of annotations, a head, and an optional body:

Find the thief: Introduction
============================

There is a small village hidden away in the mountains.

Gives the following output:

test.rst
 1:1   suggestion  'Top-level entities' should use sentence-style capitalization.            Microsoft.Headings
 6:1   suggestion  'Non-member predicates' should use sentence-style capitalization.         Microsoft.Headings
 11:1  suggestion  'Find the thief: Introduction' should use sentence-style capitalization.  Microsoft.Headings

As far as I can tell, all of these headings use sentence case already. Is there anything that I could change or configure to stop it flagging these headings?

jdkato commented 5 years ago

This appears to be a bug with the NLP library Vale uses: words like 'Top-level' aren't split into two tokens, so 'Top-Level' becomes the expected capitalized form.

I'll fix this in the next release of Vale, which I should get out in a day or two.

felicitymay commented 5 years ago

That sounds great. Many thanks for looking into this so quickly. I really appreciate it.

Regarding the colon followed by a capital letter, is this expected to be flagged up as wrong?

jdkato commented 5 years ago

Regarding the colon followed by a capital letter, is this expected to be flagged up as wrong?

I think it depends on the style—e.g., Microsoft says no, while Google says yes (even though they both want sentence-cased headings).

The goal here should be to make this configurable at the rule level, I suppose.

jdkato commented 5 years ago

Both issues should be fixed in v0.4.2.

You'll need to be using Vale v1.7.0 for the fixes to apply.