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 On Wed, Aug 1, 2012 at 8:15 PM, Marco Peereboom <marco at peereboom.us> wrote:> 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! > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
On 08/02/12 13:42, Daniel Dunbar wrote:> 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?