Mismatch between documentation and code concerning categories
- 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