[poppler] poppler-utils manpages

[Albert Astals Cid]

El dijous, 7 de desembre de 2017, a les 14:56:34 CET, Jan Stary va escriure:
> Dear authors of poppler,

Hey, i just realized we never answered you.

> 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.

I do see the benefit of the new syntax, it's more structure oriented than 
markup oriented, however my main concern is "the docs as of they are now 
work", i.e. the syntax may not be great but it shows fine and we hardly edit 
the docs at all, so changing to the "new and better" format, while cool, opens 
a gate for regressions while really not giving us much since we don't edit the 
man pages much.

Unless anyone else from the team really wants this i think I'll suggest not 
changing them.

Thanks for your time!

Cheers,
  Albert

> 
> 	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
> _______________________________________________
> poppler mailing list
> poppler at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/poppler