search

dharple / detox

Tames problematic filenames
BSD 3-Clause "New" or "Revised" License
332 stars 19 forks source link

Update manpages #22

Closed dharple closed 3 years ago

dharple commented 3 years ago

Look in to a tool to assist with managing the man pages for detox. Ronn (https://github.com/rtomayko/ronn) looks interesting.

dharple commented 3 years ago

To go from *roff to markdown, I was considering writing a sed script. This looks like it might do most of the work:

https://github.com/mle86/man-to-md

also, pandoc might work?!

https://github.com/ueberdosis/alldocs.app

dharple commented 3 years ago

man-to-md does not support mdoc (mandoc) macros, but at least has the decency to say so.

pandoc doesn't support them, either, but it just skips them silently, resulting in half a manpage being exported.

mandoc appears to work, and get close enough for this purpose.

http://man.openbsd.org/mandoc.1

That works, and generates a file that can be cleaned up and formatted for use with ronn-ng. (https://github.com/apjanke/ronn-ng).

I'm no longer convinced that it's the correct way to go, though. The man pages that come out of ronn-ng look decent enough, but it's generating straight *roff output, not mandoc output, and my concern is that some functionality might not work. For example, the references to other man pages are not written out as .Xr, and I'm not sure if that will still generate links when converting a man page to HTML.

e.g.

.SH "SEE ALSO"
inline\-detox(1), detoxrc(5), detox\.tbl(5)\.

vs the original

.Sh SEE ALSO
.Xr inline-detox 1 ,
.Xr detoxrc 5 ,
.Xr detox.tbl 5 .