layout: true class: typo, typo-selection --- name: first class: center, middle, inverse background-image:url(https://devlog.gitlabpages.inria.fr/2023-seminaire/images/bourse_nuit.jpg) .abs-layout.p-m.top-0.left-0.height-10.width-100.oc-bg-black.opacity-80.center[] .abs-layout.p-m.top-10.left-0.height-80.width-100.oc-bg-black.opacity-90.center[ ## Using Vale to Improve your Project Documentation SED de Paris .font-xxl[ .orange[Mauricio DIAZ ] ] .font-m[.orange[15/04/2024 ]] .affiliations[ ![Inria](imgs/inria-logo.png) ] ] .abs-layout.p-m.top-90.left-0.height-10.width-100.oc-bg-black.opacity-80.center[] <!-- .abs-layout.top-70.left-5.width-95.center[ ![Banner](imgs/AI_Community_small.png)] --> ??? Comments --- class: middle name: plan # [Install Vale (really easy!)](https://vale.sh/) ![Package_Vale](imgs/vale_install.png) --- class: middle name: start # Quick start ```bash $ cd some-project # You'll need to create this file $ cat .vale.ini ... $ vale sync ... $ ls styles ... $ vale README.md ``` --- class: middle name: # Example initialization file Example `.vale.ini` file ```toml StylesPath = styles Vocab = Blog [*.md] BasedOnStyles = Vale, write-good ``` --- class: middle name: style # Styles Collections of individual writing rules packaged together to enforce guidelines from a third-party organization or tool. ```text $ tree styles ├───Microsoft ├───config/vocabularies/ │ ├───Blog │ └───Marketing └───write-good ``` --- name: formats # Formats - **Markdown** : several flavors. The supported extensions are `.md`, `.mdown`, `.markdown`, and `.markdn` - **HTML** : HTML5 support is built in. The supported extensions are `.html`, `.htm`, `.shtml`, and `.xhtml` - **reStructuredTex**. The supported extensions are `.rst` and `.rest`. - **AsciiDoc**. The supported extensions are .adoc, .asciidoc and .asc - **XML** - **Org** - **Code**: source code comments in different programming languages. --- name: cas ## Typical user case ![User Case](https://miro.medium.com/v2/resize:fit:1400/format:webp/1*pSbpf1OgyM0f_BeOut4ITg.png) --- name: example ##### vale-boilerplate This is an example of the basic components of Vale's configuration: a `StylesPath` (`/styles`), a configuration file (`/.vale.ini`). Try it out by running `vale index.md` from your command line. Vale is capable of "understanding" markup, allowing it to intelligently lint prose without generating hundreds of markup-related false positives. For example, consider the following [`write-good`](https://github.com/btford/write-good) style violations: > This sentence is extremely good. When using the `write-good` style, this sentence will generate a warning by default (`'extremely' is a weasel word!`). However, if we format `extremely` as inline code, we will no longer receive a warning: > This sentence is `extremely` good. You can also use inline comments to control Vale's behavior: <!-- vale off --> This also works for code blocks and you can even write rules that only activate in certain sections of markup (e.g., headings or block quotes). <!-- vale on --> This is is another sentence with an error. --- name: inverse class: center, middle, inverse # Thanks! ---