OneSentencePerLine.yml Vale rule does NOT catch all occurrences

[aneta-petrova]

https://github.com/theforeman/foreman-documentation/blob/master/.vale/styles/foreman-documentation/OneSentencePerLine.yml introduced a project-specific Vale rule to report multiple sentences on one line. Test PR #4468 shows that the rule doesn't report everything it should.

The current rule is as follows:

# Report that a line includes more than one sentence.
---
extends: occurrence
message: "Write one sentence per line."
level: error
scope: paragraph
max: 1
token: '[\w\)\]"][.!?](?: |$)'

It misses some occurrences, as evidenced by #4468.

An alternative I tried was:

# Report that a line includes more than one sentence.
---
extends: occurrence
message: "Write one sentence per line."
level: error
scope: paragraph
max: 1
token: '[.!?](?: |$)'

This alternative reports some false positives, from what I can see it happens when a procedure includes a snippet, like here:

foreman-documentation/guides/common/modules/proc_creating-hosts-on-proxmox.adoc

Line 23 in 823df92

. From the *Deploy on* list, select your Proxmox compute resource.

[aneta-petrova]

@apinnick asked about the false positives produced by the alternative regex token: '[.!?](?: |$)' (the one that's currently not used) so I'll share a bit more on that.

In proc_generating-a-host-boot-disk.adoc:

.Procedure
include::snip_steps-create-a-host-tab-host.adoc[]
include::snip_steps-create-a-host-tab-interfaces.adoc[]
. Click the *Operating System* tab.      <--- THIS IS AN ERROR
Verify that all fields contain correct values.
. Click *Resolve* in *Provisioning Templates* to check the new host can identify the right provisioning templates to use.
+
For more information about associating provisioning templates, see xref:associating-templates-with-operating-systems[].
ifdef::katello,satellite,orcharhino[]
include::snip_step-parameter-ak.adoc[]
endif::[]
. Click *Submit* to save the host details.      <--- THIS IS AN ERROR
This creates a host entry and the host details page appears.
. Download the boot disk from {ProjectServer}.
On the host details page, click the vertical ellipsis and select *Host '_My_Host_Name_' image*.

From proc_creating-hosts-on-vmware.adoc:

.Procedure
include::snip_steps-create-a-host-tab-host.adoc[]
. From the *Deploy on* list, select the VMware vSphere connection.      <--- THIS IS AN ERROR
. From the *Compute Profile* list, select a profile to use to automatically populate virtual machine-based settings.
include::snip_steps-create-a-host-tab-interfaces.adoc[]
. Click the *Operating System* tab, and confirm that all fields automatically contain values.
. Select the Provisioning Method that you want:
+
* For network-based provisioning, click *Network Based*.
* For image-based provisioning, click *Image Based*.
ifdef::satellite[]
* For boot-disk provisioning, click *Boot disk based*.
endif::[]
ifndef::satellite[]
* If the `foreman_bootdisk` plugin is installed, and you want to use boot-disk provisioning, click *Boot disk based*.
endif::[]
+
. Click *Resolve* in *Provisioning templates* to check the new host can identify the right provisioning templates to use.      <--- THIS IS AN ERROR
. Click the *Virtual Machine* tab and confirm that these settings are populated with details from the host group and compute profile.
Modify these settings to suit your requirements.
ifdef::katello,satellite,orcharhino[]
include::snip_step-parameter-ak.adoc[]
endif::[]
. Click *Submit* to provision your host on VMware.

And there are a few other procedures like this (not many). It looks like when a procedure contains an include statement, some steps that follow get reported as one-sentence-per-line violations. When I add a blank line after that include statement, the errors disappear.

[maximiliankolb]

When I add a blank line after that include statement, the errors disappear.

Is this something that we can really safely* do everywhere? I could create a small PoC and then we could check if GHA reports any diff.

* as in does it break lists, indentation, etc?

[apinnick]

If you add blank lines after snippets, within a procedure, that will probably break the numbering. It would be safer to add an exception for lines beginning with "include::".

AFAIK, the "blank line required between includes" Vale rule is only applied to assemblies, so it should be OK to do this in procedures.

[apinnick]

token: '[.!?](?: |$)'

Re: false positives. I had a closer look. I think this rule was triggered by the . at the start of the step.