# Converting a man page with pandoc



## eeg3 (Jan 2, 2013)

A port I am working on requires the usage of 'pandoc' (textproc/hs-pandoc) to convert its man page from source to a usable format. Installing pandoc results in a large amount of additional software being installed, so it seems nonoptimal to go through the trouble of installing it just to convert one man page in a port that otherwise has no dependencies.

What is the recommended, proper way to handle this?


----------



## cpm@ (Jan 2, 2013)

Can be used for this purpose, troff(1), the troff processor.

The GNU Troff Manual http://www.gnu.org/software/groff/manual/html_node/.


----------



## wblock@ (Jan 2, 2013)

groff(1) is used by the system:
`% groff -Tascii -mdoc /usr/src/bin/ls/ls.1`

But it depends on what the port is doing.


----------



## eeg3 (Jan 2, 2013)

wblock@ said:
			
		

> groff(1) is used by the system:
> `% groff -Tascii -mdoc /usr/src/bin/ls/ls.1`
> 
> But it depends on what the port is doing.



The application wants to use pandoc to convert a man page from Markdown format to *roff format. I'm not sure if there's an alternative method to convert it without install pandoc, or if I should try something like converting it with pandoc then doing a patch from the markdown format to the working format instead of using a converter.


----------



## cpm@ (Jan 2, 2013)

Manual pages are stored as troff source files. The manual page is a single file even if the printed form is several pages long. The formatting macros are documented in groff_man(7).

A little bit of history:


> The first manual packages written are said to be authored by Dennis Ritchie and Ken Thompson in 1971. The formatting software used was troff, and that format continues to be used to this day, although the tools may be different. The text formatting tool on Linux systems is now groff, with the leading 'g' coming from GNU. groff's existence is owed to the fact that when troff was written, terminals meant something different in terms of capabilities than what they mean today. Another strong incentive for the GNU project to create groff was troff's proprietary license. troff still lives on on other Unix systems, like OpenSolaris or Plan9, although under open source licenses.



More about concept and history of *roff, read man roff(7).


----------



## wblock@ (Jan 2, 2013)

eeg3 said:
			
		

> The application wants to use pandoc to convert a man page from Markdown format to *roff format. I'm not sure if there's an alternative method to convert it without install pandoc, or if I should try something like converting it with pandoc then doing a patch from the markdown format to the working format instead of using a converter.



If it's a one-time conversion, including the converted version seems reasonable.  There may be reasons it is not done that way, like licensing.


----------

