(no subject)

Hello Tom,

firstly, than you for bmf(1). It nust have been out of
sheer ignorance that I have stayed with bogofilter for so long.

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.

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