llvm dev - Aug 2012 - [LLVMdev] 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

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?