Man page now in rst format (WAS: Re: RFH: manpages in markdown)

[Thomas Adam]

On Mon, Apr 04, 2016 at 11:14:59PM +0100, Thomas Adam wrote:
> Hi all,
> 
> I've started to look at moving away from using docbook for man page
> generation, and instead using markdown as the base format which can then be
> converted to nroff and HTML, etc.

So I've looked again.  markdown is an OK format for this, but the generation
of markdown -> nroff is far from perfect.

Thankfully, there's RST (http://docutils.sourceforge.net/rst.html) which can
be used instead; similar to Markdown if nothing else.  On most systems,
there's rst* programs from the 'python-docutils' package which we can use to
provide the conversion.

To that end, I've removed everything in doc/* and instead, added a 'manpages'
directory with a single file in there which is the basis file for the fvwm man
page.

The conversion was automatic from HTML.  It will need a few tweaks, but
running:

rst2html manpages/fvwm.rst > manpages/fvwm.1

and then viewing the man page:

mandoc ./manpages/fvwm.1 | less

is a good start.

Anyone who wants to pick this up, do please let me know.  I'll also add this
into the the build at some point, assuming people are happy with this as a way
forward.

Historically, writing the documentation has been a reason for turning
developers away.  I hope using RST simplifies that.

-- Thomas Adam

RFH: manpages in markdown

[Thomas Adam]

Hi all,

I've started to look at moving away from using docbook for man page
generation, and instead using markdown as the base format which can then be
converted to nroff and HTML, etc.

Using markdown for this seems sensible---using just nroff (or my preference,
mdoc) is one solution, but not as accessible to everyone, and since we've a
*lot* of options in FVWM, the documentation needs to be easier to manipulate
and have others contribute to, hence why I'm keen to go with plain text in
this regard.

So far, I've got something lashed together, but it is just mechanical
conversions at the moment.  There's a lot more that needs to happen which I'll
outline below.  However, I'm hoping I'm not the person to do this, although
I'll happily help/mentor anyone who wishes to pick up from where I've started.

What I've done so far is used pandoc to convert the existing Docbook files
(XML) to Markdown.  I've not checked extensively whether this was successful,
but by-and-large it seems to have been.

Then, I moved all the generated files to a new top-level directory, "manpages"
and added a file in there called ORDER which details how the Markdown files
should be catted together to form one huge markdown file which will be the
fvwm man page.

There's a script called 'generate_manpages.sh' which does all of this
mechanically.   Run it from within the manpages directory.

The conversion of markdown -> nroff is done using a program called 'ronn',
found here:

https://github.com/rtomayko/ronn

But all is not perfect.   Install 'ronn' and see for yourself what it spits
out.

Anyone who's interested in this needs to:

* Audit the markdown files to ensure the conversion is complete;
* Think whether we need all of the individual .md files or whether we can
  amalgamate.  I suspect we can quite a bit.  I'm keen not to see one huge
  file again.
* Fix up a lot of warnings from the markdown files converting to nroff;
* Hook these things into the buildsystem, removing the Docbook files.

Any questions, do please ask.  Any offers of help, *definitely* let me know.
You can find my efforts here:

https://github.com/fvwmorg/fvwm/tree/ta/docs-to-md

Specifically, the 'ta/docs-to-md' branch.

Kindly,
Thomas Adam