jgm / jgm/gitit

Mismatch between documentation and code concerning categories

Open
#309 1 comment 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Haskell
Stars
2.3k
Forks
231
PR merge metrics
No merged PRs in 30d

Description

Gitit's README file claims that page metadata may contain a keyword for categories which is followed by "a space or comma separated list". Notice _or_.

However function `splitCategories` in `Network.Gitit.Util` converts commas, periods, colons and semicolons to spaces and then splits the string.

So either the function should match documentation and split only on spaces _or_ commas or, alternatively, documentation should be amended so as to make clear that different delimiters are possible and practically interchangeable.

I came across this behaviour when trying to use comma-separated items consisting of multiple words as category names. For example: `categories: John Doe, Jane Doe` is parsed as four categories and not as two as I expected.

[Added later] Moreover, `Network.Gitit.Page.hs` claims in comments that "[t]he categories in the @categories@ field should be separated by spaces. Commas will be treated as spaces", contradicting documentation.

Contributor guide

No contributing guide indexed for this repository

Research direction

Read the README description of category metadata alongside splitCategories in Network.Gitit.Util and the comments in Network.Gitit.Page.hs. Determine which delimiter behavior is intended, then align the documentation and code so the handling of comma-separated multi-word categories is consistent; verify the example from the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
haskell
Domain
backend, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.