[poppler] poppler-utils manpages

[Jan Stary]

Dear authors of poppler,

currently, the manpages that come with poppler-utils
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.

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
- both formats can be rendered with man(1)
or processed into plaintext, html, pdf, or ps
(or even into markdown, with mandoc(1)).

The main point 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, env variables, etc.

See http://mdocml.bsd.lv for a thorough discussion
of the many benefits of such a markup - most important
of which is better readability and writability.

See below for a rewrite of pdfunite.1 and pdfseparate.1
as an example of what I have in mind.

Please let me know if you are interested.

	Jan


.Dd December 7, 2017
.Dt PDFUNITE 1
.Os
.Sh NAME
.Nm pdfunite
.Nd merge PDF files
.Sh SYNOPSIS
.Nm pdfunite
.Op Fl h
.Op Fl v
.Ar input1.pdf
.Ar ...
.Ar inputN.pdf
.Ar oputput.pdf
.Sh DESCRIPTION
.Nm
merges several PDF (Portable Document Format) files
in order of their occurence on command line into one PDF output file.
The input files must not be encrypted.
.Pp
The options are as follows.
.Bl -tag -width Ds -compact
.It Fl h
Print usage information.
.It Fl v
Print copyright and version information.
.El
.Sh SEE ALSO
.Xr pdfseparate 1
.Pp
.Lk http://poppler.freedesktop.org



.Dd December 7, 2017
.Dt PDFSEPARATE 1
.Os
.Sh NAME
.Nm pdfseparate
.Nd extract pages from a PDF document
.Sh SYNOPSIS
.Nm pdfseparate
.Op Fl h
.Op Fl v
.Op Fl f Ar first
.Op Fl l Ar last
.Ar input
.Ar name-pattern
.Sh DESCRIPTION
.Nm
extracts individual pages from a PDF document.
The input document must not be encrypted.
.Pp
The pages extracted from
.Ar input
are saved in individual output files named like
.Ar name-pattern .
The
.Ar name-pattern
must contain a
.Dq %d
placeholder if more than one page is to be be extracted.
The
.Dq %d
will be replaced by the original page number.
.Pp
The options are as follows:
.Pp
.Bl -tag -width 8n -compact
.It Fl f Ar first
The first page to extract (start of input by default).
.It Fl l Ar last
The last page to extract (end of input by default).
.It Fl h
Print usage information.
.It Fl v
Print copyright and version information.
.El
.Sh EXAMPLES
.Dl $ pdfseparate file.pdf file-%d.pdf
.Pp
extracts all pages from
.Pa file.pdf .
If
.Pa file.pdf
has 3 pages, the resulting files will be named
.Pa sample-1.pdf ,
.Pa sample-2.pdf
and
.Pa sample-3.pdf .
.Sh SEE ALSO
.Xr pdfunite 1
.Pp
.Lk http://poppler.freedesktop.org