bmf manpages

Hello Tom,

currently, the manpages that come with bmf(1)
are written in the traditional man(7) markup language.
I am proposing  to rewrite them into the semantic markup
of the mdoc(7) language. I am willing to do the work.

The main point here is that mdoc(7) allows for constructs like
 
 	.Op Fl f Ar arg
 
meaning

 	there is an optional 'f' flag
 	which takes an 'arg' argument
 
as opposed to
 
 	switch to italics, type a bracket, a dash, "f",
 	then switch to boldface and type "arg"
 
in the physical roff markup of man(7).
Similarly for other constructs like cross-referenes,
filenames, author emails etc.
 
See http://mdocml.bsd.lv for a thorough discussion
of the many benefits of such a markup - most important
of which is the better readability and writability.

Both the man(7) and mdoc(7) languages have been around for decades,
and are supported by the prevalent formatters: groff(1) on most Linuxes
and mandoc(1) on the *BSDs and some others. In particular, there is
nothing to install or reconfigure on most systems;
the pages in either language just render in man(1).

See below for a rewrite of bmfconv.1
as an example of what I have in mind,
and some comments.

Please let me know if you are interested.

(I have more things to do with bmf; I am starting with
cleaning up the manpages as it seemed the easiest.)

 	Jan
 
 
The original manpage says

 	Generated by db2man.xsl. Don't modify this, modify the source.

I don't believe it's true (so I have removed it).
If I am not mistaken, bogofilter documentation is originaly in docbook
and the *.1 are generated from that. It seems that the bmf manpages
are (copypasted and) written in man(7) directly. Or is thare really
a XML source to the *.1 manpages of bmf?

I have taken the liberty of adding SEE ALSO and EXAMPLES,
and renamed RETURN VALUES to EXIT STATUS (it's a program, not a function).


.Dd September 20, 2016
.Dt BMFCONV 1
.Os
.Sh NAME
.Nm bmfconv
.Nd convert between bmf databases
.Sh SYNOPSIS
.Nm
.Op Fl d Ar db
.Op Fl f Ar fmt
.Op Fl eihv
.Sh DESCRIPTION
.Nm
converts
.Xr bmf 1
token databases between supported formats.
It can import flat text files into databases
and export databases into flat text files.
The text files used in import and export operations
are read and written in the current directory.
.Pp
The options are as follows:
.Pp
.Bl -tag -width Ds -compact
.It Fl d Ar db
Specify directory or database name.
.It Fl f Ar fmt
Specify database format:
.Dq db
for libdb or
.Dq mysql
for MySQL.
.It Fl e
Export to
.Pa goodlist.txt
and
.Pa spamlist.txt
.It Fl i
Import from
.Pa goodlist.txt
and
.Pa spamlist.txt
.It Fl h
Display a short help.
.It Fl v
Display version information.
.El
.Sh FILES
.Bl -tag -compact -width spamlist.txt
.It Pa goodlist.txt
Text file of good tokens.
.It Pa spamlist.txt
Text file of spam tokens.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
.Dl $ cd ~/.bmf/
.Dl $ bmfconv -e
.Sh SEE ALSO
.Xr bmf 1
.Sh AUTHORS
.An Tom Marshall Aq Mt [email protected]
.Sh BUGS
The import/export file paths are hardcoded.

------------------------------------------------------------------------------