[neomutt-devel] New Project: Mutt manual/manpage documentation

[Thomas Adam]

Hi all,

Today, I'm announcing a project which I'll be leading to modernise the Neomutt
documentation.

Why?  For quite some time, Mutt (and hence Neomutt) have been using a
complex system of Docbook/XML, groff (ripped out of some of the code), and
other things.  Unfortunately, the cost of maintaining this both in terms of
the build system---and perhaps more importantly---the ease with which
documentation can be added/changed, means that we're looking at alternatives.

To that end, I'm going to lead this project through a transition to accomplish
the following high-level goals:

* Move the manual from Docbook/XML to Markdown;   [Done]
* Move the man pages from groff to Markdown.
* Cleave the embedded documentation out of the code and into a standalone
  section (again; just another Markdown section)
* Start splitting out the manual from one huge .md file into sections.
* Eventually switch-over Neomutt to using the documentation we've produced!

The generated result of these markdown files will be .html for the manual, and
a .man file for the relevant man pages.

For the time-being, I'm concentrating on the manual -- the man pages are a
longer-term goal which will probably be somewhat easier to do, since the
manual is the slightly larger beast to tackle first of all.

What I've done is create a separate repository to isolate the work that
happens on the documentation [0].  This will allow us to have independent
collaboration.  Eventually, we'll be able to switch Neomutt's build system
over to using this, but for now it means Neomutt can carry on with what it has
for now and we'll just have to play catch-up as/when things are added to the
documentation.

Furthermore, I've gone ahead and generated a one-shot approach that rendered
the manual from XML to Markdown [1] and plonked the result in the repository.
It looks ugly, which is fine, but the important thing is that the information
is present and correct.

What I want from those people who are interested is:

* A list of ideas about what they want to see from the documentation;
* A list of offers to help and with what.

For inspiration, I've already started collating a list of ideas/tasks in the
repository's issue tracker [2].

So -- do please take a look.  If you have any questions, or want to help, do
please get in touch!

Kindly,
Thomas

[0] https://github.com/neomutt/neomutt-docs
[1] https://github.com/neomutt/neomutt-docs/blob/master/manual/manual.md
[2] https://github.com/neomutt/neomutt-docs/issues