pods

To my absolute dismay I found out that the latest llvm docs are in rst format. I tried a couple of rst to man converters and the results are pretty bad. rst2man sort of works but spits out a lot of errors and the man pages don't look very good. sphinx crashes and is really too heavy. pandoc, haskell, right.

I'd like to plead with the forces that be to bring back the pods. Pods aren't great but pod2man is at least a standard UNIX utility and one can convert it to many other formats easily.

Help a UNIX brother out!

I checked all of the man pages generated using Sphinx and I thought that:

1. They all looked mostly identical.

2. When they didn't, I was equally happy with the Sphinx output.

Can you provide two specific .1 files one from POD and one from Sphinx
that shows an issue you are concerned about.

I haven't encountered problems with "Sphinx crashing" generating man
pages. This sounds like something that you should file a bug for.

- Daniel

I checked all of the man pages generated using Sphinx and I thought that:

1. They all looked mostly identical.

2. When they didn't, I was equally happy with the Sphinx output.

I couldn't get Sphinx to work. It would always bomb out so I gave up.

Also sphinx is pretty heavy weight which is not helpful for our environment. We use clang/llvm as the base compiler for bitrig and we use packages to do binary distribution. Every additional run/compile time tool we have to add is one too many for various reasons.

I used rst2man and it missed some bits and pieces and pages like llvm-nm were mangled pretty good. I did see that there is a new version of it so I will try that as a last resort.

Can you provide two specific .1 files one from POD and one from Sphinx
that shows an issue you are concerned about.

I would if I was smart enough to make sphinx work without crashing.

I haven't encountered problems with "Sphinx crashing" generating man
pages. This sounds like something that you should file a bug for.

Why were the pods dropped anyway?

When I was updating the FreeBSD devel ports recently I found that to be
the case with a version from 2011, updating to a more recent version
(1.1.3) resulted in manpages building fine.

--Brooks