Merge pull request #64 from themr0c/introduce-crontributor-guide

.htmltest.yml

@@ -19,4 +19,5 @@ ExternalTimeout: 60 # (seconds) default is 15.
 IgnoreURLs:
   - https://cse.google.com/cse.js
   - https://github.com/vale-at-red-hat/vale-at-red-hat
+  - https://github.com/Vale-at-Red-Hat/vale-at-red-hat
   - https://marketplace.visualstudio.com

antora.yml

@@ -18,6 +18,7 @@ display_version: main
 start_page: end-user-guide:introduction.adoc
 nav:
   - modules/end-user-guide/nav.adoc
+  - modules/contributor-guide/nav.adoc
 asciidoc:
   attributes:
     # for antora

modules/contributor-guide/nav.adoc

@@ -0,0 +1,6 @@
+.Contributor guide
+
+* xref:contributing.adoc[]
+* xref:vale-at-red-hat-repository.adoc[]
+* xref:extending-the-spelling-rule.adoc[]
+* xref:extending-the-redhat-style.adoc[]

modules/contributor-guide/pages/extending-the-redhat-style.adoc

@@ -0,0 +1,17 @@
+// Metadata for Antora
+:navtitle: Extending rules
+:keywords: contributing, style, rules
+// :page-aliases: 
+// End of metadata for Antora
+
+:parent-context-of-extending-styles: {context}
+
+[id="extending-the-redhat-style_{context}"]
+= Extending the _RedHat_ style
+
+:context: extending-the-redhat-style
+
+include::partial$proc_extending-the-redhat-style.adoc[leveloffset=+1]
+
+:context: {parent-context-of-extending-styles}
+

modules/contributor-guide/pages/extending-the-spelling-rule.adoc

@@ -0,0 +1,17 @@
+// Metadata for Antora
+:navtitle: Extending _Spelling_
+:keywords: contributing, spelling-rule
+// :page-aliases: 
+// End of metadata for Antora
+
+:parent-context-of-extending-the-spelling-rule: {context}
+
+[id="extending-the-spelling-rule_{context}"]
+= Extending the _Spelling_ rule
+
+:context: extending-the-spelling-rule
+
+include::partial$proc_extending-the-spelling-rule.adoc[leveloffset=+1]
+
+:context: {parent-context-of-extending-the-spelling-rule}
+

modules/contributor-guide/pages/vale-at-red-hat-repository.adoc

@@ -0,0 +1,18 @@
+// Metadata for Antora
+:navtitle: Repository
+:keywords: vale-at-red-hat-repository, repository, concept
+// :page-aliases: 
+// End of metadata for Antora
+
+:parent-context-of-vale-at-red-hat-repository: {context}
+
+[id="vale-at-red-hat-repository_{context}"]
+= _Vale at Red Hat_ repository
+
+:context: vale-at-red-hat-repository
+
+include::partial$con_vale-at-red-hat-repository.adoc[leveloffset=+1]
+
+
+:context: {parent-context-of-vale-at-red-hat-repository}]
+

modules/contributor-guide/partials/con_vale-at-red-hat-repository.adoc

@@ -0,0 +1,16 @@
+:_module-type: CONCEPT
+
+[id="con_vale-at-red-hat-repository_{context}"]
+= link:{repository-url}[_{repository-name}_ repository]
+
+The link:{repository-url}[_{repository-name}_ repository] contains resources to validate language in documentation projects using Vale:
+
+* xref:end-user-guide:redhat-style-for-vale.adoc[] in the `.vale/styles/RedHat` directory
+* xref:end-user-guide:glossary.adoc#vale-configuration-file_{context}[Vale configuration files] for usage in a local environment or by the GitHub Action.
+* xref:end-user-guide:introduction.adoc[End-user guide]
+* xref:contributor-guide:contributing.adoc[Contributor guide]
+
+
+.Additional resources
+
+* link:{repository-url}[{repository-name} repository]

modules/contributor-guide/partials/con_vale-configuration-file.adoc

@@ -0,0 +1,17 @@
+:_module-type: CONCEPT
+
+[id="con_vale-configuration-file_{context}"]
+= Vale configuration file
+
+The Vale configuration file `.vale.ini` defines:
+
+* File names patterns to match files to validate
+* Active styles and vocabulary
+* Custom content patterns to modify scoping behavior
+
+.Additional resources
+
+* xref:getting-started-with-vale.adoc[]
+* xref:adding-vale-configuration-to-a-project.adoc[]
+* link:https://docs.errata.ai/vale/config[Vale documentation - Configuration]
+

modules/contributor-guide/partials/proc_creating-a-vocabulary-for-a-project.adoc

@@ -0,0 +1,44 @@
+:_module-type: PROCEDURE
+
+[id="proc_creating-a-vocabulary-for-a-project_{context}"]
+= Creating a vocabulary for a project
+
+Consider adding a *Vocabulary* to your project when missing words in the Vale dictionary are causing *Spelling* errors and the word is too specific to benefit to other projects.
+
+.Prerequisites
+
+* xref:end-user-guide:getting-started-with-vale.adoc[]
+* xref:end-user-guide:understanding-vale-output.adoc[]
+* xref:end-user-guide:defining-a-vale-onboarding-strategy.adoc[]
+
+.Procedure
+
+* Create or edit the Vocabulary for your project: create or edit the `.vale/styles/Vocab/__<Project>__/accept.txt` file and add the missing word. Ensure the entry is not case-sensitive.
++
+.Entry in the vocabulary, not case-sensitive
+----
+[Pp]odman
+----
+
+
+* Register the Vocabulary in the `.vale.ini` file
++
+[source,ini,subs="+quotes,+attributes,+macros"]
+----
+Vocab = __<Project>__
+----
+
+.Verification
+
+* Run the `vale` command on a content file containing the word which was missing.
++
+[subs="+quotes,+attributes"]
+----
+$ cd __<project_directory>__
+$ vale __<filename>__
+----
+
+.Additional resources
+
+* link:https://docs.errata.ai/vale/vocab[Vale documentation - Vocabularies]
+

modules/end-user-guide/partials/proc_extending-styles.adoc → modules/contributor-guide/partials/proc_extending-the-redhat-style.adoc

@@ -1,7 +1,7 @@
 :_module-type: PROCEDURE
 
-[id="proc_extending-styles_{context}"]
-= Extending styles
+[id="proc_extending-the-redhat-style_{context}"]
+= Extending the _RedHat_ style
 
 Consider extending styles when:
 
@@ -17,13 +17,13 @@ Consider the best approach:
 
 .Prerequisites
 
-* xref:getting-started-with-vale.adoc[]
-* xref:understanding-vale-output.adoc[]
-* xref:defining-a-vale-onboarding-strategy.adoc[]
+* xref:end-user-guide:getting-started-with-vale.adoc[]
+* xref:end-user-guide:understanding-vale-output.adoc[]
+* xref:end-user-guide:defining-a-vale-onboarding-strategy.adoc[]
 
 .Procedure
 
-* Edit the `.vale/styles/Red-Hat-CCS/` file and add the missing word. 
+* Edit the `.vale/styles/RedHat/_<StyleName>_.yml` file and add the missing word. 
 
 .Verification
 

modules/end-user-guide/partials/proc_extending-the-spelling-rule.adoc → modules/contributor-guide/partials/proc_extending-the-spelling-rule.adoc

@@ -3,13 +3,18 @@
 [id="proc_extending-the-spelling-rule_{context}"]
 = Extending the *Spelling* rule
 
-Consider extending the *Spelling* rule in the link:{repository-url}[{repository-name} repository] when missing words in the Vale dictionary are causing *Spelling* errors and the fix could benefit to other projects. For example: product and tool names, common terms specific to the software industry.
+Consider extending the *Spelling* rule in the link:{repository-url}[{repository-name} repository] when:
+
+* Missing words in the Vale dictionary are causing *Spelling* errors 
+* Adding the word will benefit to other projects. For example: product and tool names, common terms specific to the software industry.
+
+When the word is too specific to benefit to other projects, consider xref:end-user-guide:creating-a-vocabulary-for-a-project.adoc[].
 
 .Prerequisites
 
-* xref:getting-started-with-vale.adoc[]
-* xref:understanding-vale-output.adoc[]
-* xref:defining-a-vale-onboarding-strategy.adoc[]
+* xref:end-user-guide:getting-started-with-vale.adoc[]
+* xref:end-user-guide:understanding-vale-output.adoc[]
+* xref:end-user-guide:defining-a-vale-onboarding-strategy.adoc[]
 
 
 .Procedure

modules/end-user-guide/partials/ref_contributing.adoc → modules/contributor-guide/partials/ref_contributing.adoc

@@ -6,15 +6,15 @@
 
 You can help by doing any of the following:
 
-* Use Vale with the style rules from the {repository-name} repository, see xref:getting-started-with-vale.adoc[]
+* Use Vale with the style rules from the {repository-name} repository, see xref:end-user-guide:getting-started-with-vale.adoc[]
 
 * link:{repository-url}/issues[Report issues and request enhancements]
 
 * Join the Slack channel, link:https://coreos.slack.com/archives/C0218RXJK5E[#vale-at-red-hat], in the CoreOS workspace.
 
-* xref:extending-the-vocabulary.adoc[]
+* xref:extending-the-spelling-rule.adoc[]
 
-* xref:extending-styles.adoc[]
+* xref:extending-the-redhat-style.adoc[]
 
 * To show appreciation and support for Joseph Kato's work on Vale, consider link:https://docs.errata.ai/vale/about#sponsors[making a donation].
 

modules/end-user-guide/nav.adoc

@@ -1,10 +1,12 @@
+.End-user guide
+
 * xref:introduction.adoc[]
+* xref:redhat-style-for-vale.adoc[]
+* xref:glossary.adoc[]
 * xref:getting-started-with-vale.adoc[]
 * xref:understanding-vale-output.adoc[]
 * xref::using-vale-in-the-ide.adoc[]
 * xref:defining-a-vale-onboarding-strategy.adoc[]
 * xref:adding-vale-configuration-to-a-project.adoc[]
+* xref:creating-a-vocabulary-for-a-project.adoc[]
 * xref:using-vale-with-a-continuous-integration-service.adoc[]
-* xref:contributing.adoc[]
-** xref:extending-the-vocabulary.adoc[]
-** xref:extending-styles.adoc[]

modules/end-user-guide/pages/extending-the-vocabulary.adoc → modules/end-user-guide/pages/creating-a-vocabulary-for-a-project.adoc

@@ -11,8 +11,8 @@
 
 :context: extending-the-vocabulary
 
-include::partial$proc_extending-the-spelling-rule.adoc[leveloffset=+1]
 include::partial$proc_creating-a-vocabulary-for-a-project.adoc[leveloffset=+1]
 
+
 :context: {parent-context-of-extending-the-vocabulary}
 

modules/end-user-guide/pages/glossary.adoc

@@ -0,0 +1,30 @@
+// Metadata for Antora
+:navtitle: Glossary
+:keywords: glossary, antora
+// :page-aliases: old-glossary
+// End of metadata for Antora
+
+:parent-context-of-glossary: {context}
+
+[id="glossary_{context}"]
+= Glossary
+
+:context: glossary
+
+include::partial$con_vale-command-line-tool.adoc[leveloffset=+1]
+
+
+include::partial$con_vale-configuration-file.adoc[leveloffset=+1]
+
+
+include::partial$con_vale-rule.adoc[leveloffset=+1]
+
+
+include::partial$con_vale-style.adoc[leveloffset=+1]
+
+
+include::partial$con_vale-vocabulary.adoc[leveloffset=+1]
+
+
+:context: {parent-context-of-glossary}]
+

modules/end-user-guide/pages/introduction.adoc

@@ -11,11 +11,8 @@
 
 :context: introduction
 
-
 include::partial$con_the-benefits-of-using-vale.adoc[leveloffset=+1]
 
-include::partial$con_glossary.adoc[leveloffset=+1]
-
 
 :context: {parent-context-of-introduction}]
 

modules/end-user-guide/pages/redhat-style-for-vale.adoc

@@ -0,0 +1,21 @@
+// Metadata for Antora
+:navtitle: RedHat Style
+:keywords: redhat-style-for-vale, antora
+// :page-aliases: old-redhat-style-for-vale
+// End of metadata for Antora
+
+:parent-context-of-redhat-style-for-vale: {context}
+
+
+[id="redhat-style-for-vale_{context}"]
+pass:[<!-- vale RedHat.Spelling = NO -->]
+= _Redhat_ style for vale
+
+:context: redhat-style-for-vale
+
+
+include::partial$con_redhat-style-for-vale.adoc[leveloffset=+1]
+
+
+:context: {parent-context-of-redhat-style-for-vale}]
+

modules/end-user-guide/pages/understanding-vale-output.adoc

@@ -7,7 +7,6 @@
 :parent-context-of-understanding-vale-output: {context}
 
 [id="understanding-vale-output_{context}"]
-
 = Understanding vale output
 
 :context: understanding-vale-output