Add markdown linter, and fix Markdown documents

.markdownlint.yml

@@ -0,0 +1,14 @@
+default: true
+ul-indent:
+    indent: 4
+
+fenced-code-language: false
+
+line_length: false
+first-line-h1: false
+no-trailing-punctuation: false
+no-inline-html: false
+commands-show-output: false
+
+# Changelog files are full of duplicate headers
+no-duplicate-header: false

.pre-commit-config.yaml

@@ -7,6 +7,11 @@ repos:
       - id: check-yaml
       - id: check-added-large-files
 
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.32.2
+    hooks:
+      - id: markdownlint-fix
+
   - repo: local
     hooks:
       - id: tests

doc/bugtracking.md

@@ -1,11 +1,13 @@
-# Introduction
+# Bugtracking
+
+## Introduction
 
 Yokadi comes with a set of commands tailored to help you track bugs. These
 commands are `bug_add` and `bug_edit`. They are similar to `t_add` and `t_edit`
 except they will ask you a few questions to help you decide which bug to fix
 next.
 
-# Entering a bug
+## Entering a bug
 
 Enter a new bug like you would enter a new task:
 
@@ -48,7 +50,7 @@ If you edit the task with `t_edit 12` you will only be able to fix the task
 title. To be asked for severity, likelihood and bug id again, use
 `bug_edit 12`.
 
-# What's next?
+## What's next?
 
 Based on the severity and likelihood, Yokadi computes the urgency of the bug.
 The formula used is:
@@ -64,7 +66,7 @@ This is based on the concept of "User Pain", as described by Danc here:
 Now, when you list your tasks with `t_list`, the most urgent tasks will be
 listed first, making it easy to fix the most important bugs first.
 
-# Behind the scenes
+## Behind the scenes
 
 Likelihood, severity and bug are stored as Yokadi keywords (Yokadi keywords can
 be associated with an integer value).
@@ -74,7 +76,7 @@ task urgency field. Yes, this means there is duplication and you may get
 likelihood/severity and urgency out of sync if you manually adjust urgency with
 `t_set_urgency`. In practice, I found it was not a problem.
 
-# Tricks
+## Tricks
 
 Here are a few tricks I came up with while using Yokadi to do bug tracking:
 

doc/dev/db-updates.md

@@ -8,7 +8,7 @@ The update process goes like this:
 
 - Copy yokadi.db to work.db
 - for each v between x and x + n - 1:
-     - run `update<v>to<v+1>.update()`
+    - run `update<v>to<v+1>.update()`
 - Create an empty database in recreated.db
 - Fill recreated.db with the content of work.db
 - If we are updating the database in place, rename yokadi.db to yokadi-$date.db

doc/dev/hacking.md

@@ -81,7 +81,7 @@ Keep import in blocks, in this order:
 Keep import blocks sorted. It makes it easier to check if an import line is
 already there.
 
-# Command docstrings
+## Command docstrings
 
 All commands are documented either through their parser or using the command
 docstring. To ensure consistency all usage string should follow the same

doc/ical.md

@@ -1,4 +1,6 @@
-# Intro
+# Ical support
+
+## Introduction
 
 This document presents how to use Yokadi with a third party calendar/todolist
 application that supports the ical format (RFC2445).
@@ -12,7 +14,7 @@ TCP port 9000:
 
     yokadid --icalserver --port=9000
 
-# Read your Yokadi tasks in a third party tool
+## Read your Yokadi tasks in a third party tool
 
 If your third party tool supports ical format and is able to read it through
 HTTP, just set it up to read on localhost:8000 (or whatever port you setup) and
@@ -24,30 +26,29 @@ If your calendar/todo tool only supports local files:
 * make a simple shell script that downloads the ical file and put it on your
   crontab. You can use wget for that:
 
-    wget -O yokadi.ical http://localhost:8000
+    wget -O yokadi.ical <http://localhost:8000>
 
 Each Yokadi task is defined as an ical VTODO object. Yokadi projects are
 represented as special tasks to which included tasks are related.
 
-# Create and update yokadi tasks from a third party tool
+## Create and update yokadi tasks from a third party tool
 
 On the same TCP socket, you can write tasks with the PUT HTTP method. Only
 new and updated tasks will be considered.
 
-# Supported third party ical tool
+## Supported third party ical tool
 
 Yokadi should support any tool which implements RFC2345. But we are not in a
 perfect world.
 
 The following tools are known to work properly with Yokadi ical server:
 
-- Kontact/KOrganizer (4.4) from the KDE Software Compilation
+* Kontact/KOrganizer (4.4) from the KDE Software Compilation
 
 If you successfully plugged Yokadi with another calendar/todolist tool, please
 let us now in order to complete this list.
 
-
-# Some security considerations
+## Some security considerations
 
 By default, the ical server only listens on localhost (loopback). You can
 bypass this restriction with the --listen switch which makes the ical server
@@ -64,5 +65,4 @@ restrict who can access to your Yokadi daemon:
 You have been warned. That's why listening only to localhost (which is the
 default) is strongly recommended.
 
-
 <!-- vim: set ts=4 sw=4 et: -->

doc/tips.md

@@ -1,13 +1,15 @@
-# Intro
+# Tips
+
+## Introduction
 
 This document presents practical advices on how to get the best out of Yokadi.
 
-# Completion
+## Completion
 
 Yokadi supports completion of command names, and in many commands it can
 complete project names. Do not hesitate to try the `[tab]` key!
 
-# Setting up a project hierarchy
+## Setting up a project hierarchy
 
 You can set up a project hierarchy by adopting a name convention. For example if
 you want to track tasks related to a program which is made of many plugins, you
@@ -20,7 +22,7 @@ For example to list all `fooplayer` related tasks you can use:
 
     t_list fooplayer%
 
-# Using keywords
+## Using keywords
 
 Keywords are great to group tasks in different ways. For example you can create
 a keyword named `phone`, and assign it to tasks which you must accomplish on
@@ -36,13 +38,13 @@ Or even nicer, directly print your list (from the shell):
 
     yokadi "t_list @diy_store --format plain" | lp
 
-# Keep track of your meetings
+## Keep track of your meetings
 
 To track my meetings, I like to use a `meeting` keyword together with an
 assigned due date. Yokadi ability to add long descriptions to tasks is also
 handy to associate address or contact information to a meeting task.
 
-# Keep track of tasks you delegate to people
+## Keep track of tasks you delegate to people
 
 When you delegate a task to someone, add a keyword with its name to the task.
 So you can check that people really do what they promise to do even if they
@@ -56,7 +58,7 @@ To check all task that Bob should have done:
 
     t_list --overdue @bob
 
-# Some useful shortcuts
+## Some useful shortcuts
 
 Yokadi relies on readline library, so you can use very useful readline
 shortcuts such as: