CMake targets for building man pages

[axw]

Summary

This adds targets to build the clang
man page, as in the corresponding Makefile.
The output is used in Debian packaging,
which is currently stuck using autotools.

[axw]

Change to use LLVM_PATH_ variable prefix.

[chandlerc]

I think the logic here should be bundled up in a macro in the LLVM cmake tree so that we can use it both for Clang's man page generation but also generating other man pages. Does that make sense?

[axw]

In D10304#185561, @chandlerc wrote:

I think the logic here should be bundled up in a macro in the LLVM cmake tree so that we can use it both for Clang's man page generation but also generating other man pages. Does that make sense?

I didn't because this is the only thing that uses pod2man or groff AFAICS, but I'll move it to LLVM to give people that option.

[silvas]

Clang's man page is the only thing that is generated like this. The rest use Sphinx's manpage output.

[axw]

In D10304#185908, @silvas wrote:

Clang's man page is the only thing that is generated like this. The rest use Sphinx's manpage output.

@chandlerc given the above, do you still want me to create a macro/function? I'm not deeply involved here, so grain of salt, but I think it'd be better to converge on one documentation tool (Sphinx) than to perpetuate use of multiple formats (Sphinx & pod2man, and whatever else there may be). I could look at rewriting the clang.pod file in Sphinx, and then use Sphinx in CMake. Is that a reasonable change?

BTW, there's this: https://llvm.org/bugs/show_bug.cgi?id=23054, so what's there seems to be broken on OS X at least, though I can't verify that.

[axw]

Closing this, will send a new diff with sphinx-based man page.

docs/CMakeLists.txt

+add_subdirectory(tools)
 
 if (DOXYGEN_FOUND)
 if (LLVM_ENABLE_DOXYGEN)
   set(abs_srcdir ${CMAKE_CURRENT_SOURCE_DIR})
   set(abs_builddir ${CMAKE_CURRENT_BINARY_DIR})
 
   if (HAVE_DOT)
     set(DOT ${LLVM_PATH_DOT})

docs/tools/CMakeLists.txt

+llvm_find_program(POD2HTML NAMES pod2html)
+if (HAVE_POD2HTML)
+  add_custom_command(
+    OUTPUT clang.html
+    DEPENDS clang.pod
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Rendering clang man page as HTML." VERBATIM
+    COMMAND
+    ${LLVM_PATH_POD2HTML} --css=${CMAKE_CURRENT_SOURCE_DIR}/manpage.css
+                          --podpath=.
+                          --htmlroot=.
+                          --infile=${CMAKE_CURRENT_SOURCE_DIR}/clang.pod
+                          --outfile=clang.html
+                          --title=clang
+  )
+  add_custom_target(clang-man-html ALL DEPENDS clang.html)
+  if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
+    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/clang.html
+            DESTINATION share/man)
+  endif()
+endif()
+
+llvm_find_program(POD2MAN NAMES pod2man)
+if (HAVE_POD2MAN)
+  add_custom_command(
+    OUTPUT clang.1
+    DEPENDS clang.pod
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Rendering clang man page." VERBATIM
+    COMMAND
+    ${LLVM_PATH_POD2MAN} "--release=clang ${CLANG_VERSION}"
+                         "--center=Clang Tools Documentation"
+                         ${CMAKE_CURRENT_SOURCE_DIR}/clang.pod > clang.1
+  )
+  add_custom_target(clang-man ALL DEPENDS clang.1)
+  if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
+    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/clang.1
+            DESTINATION share/man)
+  endif()
+
+  llvm_find_program(GROFF NAMES groff)
+  if (HAVE_GROFF)
+    add_custom_command(
+      OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/clang.ps
+      DEPENDS clang.1
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+      COMMENT "Rendering clang man page as postscript." VERBATIM
+      COMMAND
+      ${LLVM_PATH_GROFF} -Tps -man clang.1 > clang.ps
+    )
+    add_custom_target(clang-man-ps ALL DEPENDS clang.ps)
+    if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
+      install(FILES ${CMAKE_CURRENT_BINARY_DIR}/clang.ps
+              DESTINATION share/man)
+    endif()
+  endif()
+endif()
+