You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2015/01/09 20:46:18 UTC
svn commit: r1650636 - in /qpid/dispatch/trunk/doc: README
book/CMakeLists.txt man/CMakeLists.txt
Author: aconway
Date: Fri Jan 9 19:46:18 2015
New Revision: 1650636
URL: http://svn.apache.org/r1650636
Log:
NO-JIRA: Remove man pagess from dispatch book, create separate HTML web pages for site.
Modified:
qpid/dispatch/trunk/doc/README
qpid/dispatch/trunk/doc/book/CMakeLists.txt
qpid/dispatch/trunk/doc/man/CMakeLists.txt
Modified: qpid/dispatch/trunk/doc/README
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/README?rev=1650636&r1=1650635&r2=1650636&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/README (original)
+++ qpid/dispatch/trunk/doc/README Fri Jan 9 19:46:18 2015
@@ -1,11 +1,28 @@
-This directory contains different kinds of documentation for Dispatch.
+<!--*-markdown-*-->
- book/ - Book-format documentation. This is published to the Qpid
- website with each new Dispatch release.
+# Documentation for dispatch
- man/ - Unix man pages. These are included in the installed files.
+Documentation is written in [markdown][] format with [pandoc][] extensions. We
+use [pandoc][] to generate formatted documentation such as man pages, HTML and
+PDF.
- notes/ - Developer notes: project information, design notes, or
- anything else that's primarily of developer interest.
+All markdown, HTML and PDF documentation is installed in the share/doc
+directory. Man pages are also installed in the standard share/man location.
- api/ - Generated API documentation.
+The Qpid website also has documentation for each release.
+
+Sub-directories:
+
+`book/`: Book-format documentation.
+
+`man/`: Unix man pages.
+
+`api/`: Generated API documentation.
+
+`notes/`: Developer notes: project information, design notes, or anything else
+that's primarily of developer interest. These are not installed.
+
+
+[markdown]: http://daringfireball.net/projects/markdown/syntax "Makrdown syntax"
+
+[pandoc]: http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown "Pandoc markdown syntax"
Modified: qpid/dispatch/trunk/doc/book/CMakeLists.txt
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/CMakeLists.txt?rev=1650636&r1=1650635&r2=1650636&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/book/CMakeLists.txt (original)
+++ qpid/dispatch/trunk/doc/book/CMakeLists.txt Fri Jan 9 19:46:18 2015
@@ -31,7 +31,7 @@ add_custom_command(
DEPENDS ${src}/schema_md.py ${schema}
)
-set(BOOK ${src}/introduction.md ${src}/using.md ${src}/addressing.md ${src}/amqp-mapping.md ${bin}/schema.md ${CMAKE_BINARY_DIR}/doc/man/manpages.md)
+set(BOOK ${src}/introduction.md ${src}/using.md ${src}/addressing.md ${src}/amqp-mapping.md ${bin}/schema.md)
# Install markdown documentation in the doc directory.
install(FILES ${BOOK} DESTINATION ${QD_DOC_INSTALL_DIR})
Modified: qpid/dispatch/trunk/doc/man/CMakeLists.txt
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/man/CMakeLists.txt?rev=1650636&r1=1650635&r2=1650636&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/man/CMakeLists.txt (original)
+++ qpid/dispatch/trunk/doc/man/CMakeLists.txt Fri Jan 9 19:46:18 2015
@@ -22,6 +22,8 @@
# If pandoc is available, also generate real man pages.
#
+find_program(PANDOC pandoc)
+
set(src ${CMAKE_CURRENT_SOURCE_DIR})
set(bin ${CMAKE_CURRENT_BINARY_DIR})
set(tools ${CMAKE_SOURCE_DIR}/tools)
@@ -37,14 +39,29 @@ macro(help2md program section path)
COMMAND ${RUN} -s "${src}/help2md.py" "${manpage}.noopt.md" "${manpage}.md" "${path}/${program}" --help
DEPENDS ${path}/${program} ${manpage}.noopt.md ${src}/help2md.py ${infile}
)
- set(MANPAGES_MD ${MANPAGES_MD} ${manpage}.md)
endmacro()
-# If pandoc is avaliable generate and install proper man files.
-find_program(PANDOC pandoc)
-if (PANDOC)
- macro(manpage program section)
- set(manpage "${bin}/${program}.${section}")
+# Generate and install a man page from markdown source
+macro(manpage program section)
+
+ set(manpage "${bin}/${program}.${section}")
+
+ # Install the plain markdown manpage.
+ install(FILES ${manpage}.md DESTINATION ${QD_DOC_INSTALL_DIR})
+ set(MANPAGES_OUT ${MANPAGES_OUT} ${manpage}.md)
+
+ # Generate HTML man page
+ add_custom_command (
+ OUTPUT ${manpage}.html ${manpage}.html.in
+ DEPENDS ${manpage}.md
+ COMMAND ${PANDOC} -f markdown -t html -o ${manpage}.html ${manpage}.md -s # Full page
+ COMMAND ${PANDOC} -f markdown -t html -o ${manpage}.html.in ${manpage}.md # Fragment
+ )
+ install(FILES ${manpage}.html DESTINATION ${QD_DOC_INSTALL_DIR})
+ set(MANPAGES_OUT ${MANPAGES_OUT} ${manpage}.html ${manpage}.html.in)
+
+ # Generate proper man pages
+ if (PANDOC)
string(TIMESTAMP date "%Y-%m-%d")
if(${section} EQUAL 8)
set(header "System Manager's Manual")
@@ -55,17 +72,14 @@ if (PANDOC)
endif()
add_custom_command (
OUTPUT ${manpage}
- COMMAND ${PANDOC} --template ${src}/man.template.pd -s -V date="${date}" -V title="${program}" -V section="${section}" -V version="${QPID_DISPATCH_VERSION}" -V header="${header}" -f markdown -t man -o ${manpage} "${manpage}.md"
- DEPENDS "${manpage}.md" "${src}/man.template.pd"
+ DEPENDS ${manpage}.md ${src}/man.template.pd
+ COMMAND ${PANDOC} --template ${src}/man.template.pd -s -V date="${date}" -V title="${program}" -V section="${section}" -V version="${QPID_DISPATCH_VERSION}" -V header="${header}" -f markdown -t man -o ${manpage} ${manpage}.md
)
- set(MANPAGES ${MANPAGES} ${manpage})
install(FILES ${manpage} DESTINATION "${MAN_INSTALL_DIR}/man${section}")
- endmacro(manpage)
-else(PANDOC)
- message("Not generating man pages, pandoc is not avaliable.")
- macro(manpage program section)
- endmacro()
-endif(PANDOC)
+ set(MANPAGES_OUT ${MANPAGES_OUT} ${manpage})
+ endif(PANDOC)
+endmacro(manpage)
+
# Shortcut to run both help2md and manpage
macro(help2man program section path)
@@ -86,20 +100,8 @@ add_custom_command(
COMMAND ${RUN} -s ${src}/qdrouterd_conf_man.py ${qdrouterd_conf_man}.md
DEPENDS ${src}/qdrouterd_conf_man.py ${schema}
)
-set(MANPAGES_MD ${MANPAGES_MD} ${qdrouterd_conf_man}.md)
manpage(qdrouterd.conf 5)
-# Generate the man page section of the book
-
-add_custom_command(
- OUTPUT manpages.md
- COMMAND ${RUN} -s ${src}/man2book.py ${MANPAGES_MD} > manpages.md
- DEPENDS ${src}/man2book.py ${MANPAGES_MD}
- )
-
-# Install all the markdown files
-install(FILES ${MANPAGES_MD} DESTINATION ${QD_DOC_INSTALL_DIR})
-
# Target to build the generated files
-add_custom_target(man ALL DEPENDS ${MANPAGES_MD} ${MANPAGES} manpages.md)
-
+message("FIXME" ${MANPAGES_OUT})
+add_custom_target(man ALL DEPENDS ${MANPAGES_OUT})
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org