Skip to content

Conversation

@01mf02
Copy link
Contributor

@01mf02 01mf02 commented Sep 30, 2024

This PR changes the format of the user manual from YAML to Markdown.
This gives a multitude of benefits, including better editor support, smaller files, better tooling, and more flexible document structure.
The idea is that manuals for old jq versions (1.3 to 1.7) remain untouched as YAML, whereas new documentation is written in Markdown (docs/content/manual/manual.md). When new features are added to jq, they can be documented in the manual with a compatibility note, which should allow to document all future jq versions in one file.

I've tried to preserve the look as much as possible, but there are still a few aesthetic differences compared to the current manual, especially concerning the styling of examples. If these are important to you, I can try to make them more similar.

A preview of the current state:

Screenshot 2024-09-30 at 17-26-31 jq Manual

What works:

  • Manpage generation
  • Test generation from manual (man.test, manonig.test)
  • Table of contents generation
  • Search index generation
  • Links to jq-play.org for running examples

What does not work:

  • Automatic detection of Pandoc to build documentation: I am not autotools wizard, so I changed documentation building by default to false. That means you need to run ./configure --enable-docs even if you have all required dependencies (i.e. Pandoc).

This was referenced Sep 30, 2024
@01mf02 01mf02 mentioned this pull request Oct 9, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant