| Message ID | 1474658228-5390-6-git-send-email-jgunthorpe@obsidianresearch.com (mailing list archive) |
|---|---|
| State | Accepted |
| Headers | show |
> rsocket.7 had an errant text substitution that never worked, it is > a good idea to have the man pages use the correct paths, so let > us have cmake run them through. > > Any man page ending in '.in' will be substituted automatically. > > Signed-off-by: Jason Gunthorpe <jgunthorpe@obsidianresearch.com> Acked-by: Sean Hefty <sean.hefty@intel.com> FWIW, I'm in favor of replacing the man pages with markdown and then generating the man pages from that. I volunteer someone else to do that work. -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, Sep 23, 2016 at 09:23:42PM +0000, Hefty, Sean wrote: > > rsocket.7 had an errant text substitution that never worked, it is > > a good idea to have the man pages use the correct paths, so let > > us have cmake run them through. > > > > Any man page ending in '.in' will be substituted automatically. > > > > Signed-off-by: Jason Gunthorpe <jgunthorpe@obsidianresearch.com> > > Acked-by: Sean Hefty <sean.hefty@intel.com> > > FWIW, I'm in favor of replacing the man pages with markdown and then > generating the man pages from that. I volunteer someone else to do > that work. I concur, and someone else should do the work .. We could begin by requiring all new man pages to be in markdown format. Do you do this in libfabric? What conversion tool do you like? I've used rst for this in the past with reasonable results.. Jason -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
> We could begin by requiring all new man pages to be in markdown > format. Do you do this in libfabric? What conversion tool do you like? We do this in libfabric. I believe we use Jekyll. Since someone else set that up, I was happy and didn't really care which conversion tool was used. :) -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
> We do this in libfabric. I believe we use Jekyll. Since someone else > set that up, I was happy and didn't really care which conversion tool > was used. :) Or maybe Jekyll does the html, and pandoc does the nroff... -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
> > On Fri, Sep 23, 2016 at 09:23:42PM +0000, Hefty, Sean wrote: > > > rsocket.7 had an errant text substitution that never worked, it is a > > > good idea to have the man pages use the correct paths, so let us > > > have cmake run them through. > > > > > > Any man page ending in '.in' will be substituted automatically. > > > > > > Signed-off-by: Jason Gunthorpe <jgunthorpe@obsidianresearch.com> > > > > Acked-by: Sean Hefty <sean.hefty@intel.com> > > > > FWIW, I'm in favor of replacing the man pages with markdown and then > > generating the man pages from that. I volunteer someone else to do > > that work. > > I concur, and someone else should do the work .. > > We could begin by requiring all new man pages to be in markdown format. > Do you do this in libfabric? What conversion tool do you like? > > I've used rst for this in the past with reasonable results.. Infiniband-diags uses rst through rst2man. But if I had to do it over I would probably do it different. rst2man is not always installed and has caused build issues for some people. Whatever tool we use I would recommend it be something common. I'm not too familiar with markdown. Is this really common now? Ira > > Jason > -- > To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the > body of a message to majordomo@vger.kernel.org More majordomo info at > http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Mon, Sep 26, 2016 at 06:30:21AM +0000, Weiny, Ira wrote: > > > > On Fri, Sep 23, 2016 at 09:23:42PM +0000, Hefty, Sean wrote: > > > > rsocket.7 had an errant text substitution that never worked, it is a > > > > good idea to have the man pages use the correct paths, so let us > > > > have cmake run them through. > > > > > > > > Any man page ending in '.in' will be substituted automatically. > > > > > > > > Signed-off-by: Jason Gunthorpe <jgunthorpe@obsidianresearch.com> > > > > > > Acked-by: Sean Hefty <sean.hefty@intel.com> > > > > > > FWIW, I'm in favor of replacing the man pages with markdown and then > > > generating the man pages from that. I volunteer someone else to do > > > that work. > > > > I concur, and someone else should do the work .. > > > > We could begin by requiring all new man pages to be in markdown format. > > Do you do this in libfabric? What conversion tool do you like? > > > > I've used rst for this in the past with reasonable results.. > > Infiniband-diags uses rst through rst2man. But if I had to do it over I would probably do it different. rst2man is not always installed and has caused build issues for some people. Whatever tool we use I would recommend it be something common. I'm not too familiar with markdown. Is this really common now? Among hipsters - yes :) > > Ira > > > > > Jason > > -- > > To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the > > body of a message to majordomo@vger.kernel.org More majordomo info at > > http://vger.kernel.org/majordomo-info.html > -- > To unsubscribe from this list: send the line "unsubscribe linux-rdma" in > the body of a message to majordomo@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html
> Infiniband-diags uses rst through rst2man. But if I had to do it over > I would probably do it different. rst2man is not always installed and > has caused build issues for some people. Whatever tool we use I would > recommend it be something common. I'm not too familiar with markdown. > Is this really common now? Only by those who want to provide actual documentation. Libfabric uses a daemon that checks for updates to the markdown pages. If it finds any, it generates the man page and commits those changes to the source tree. So the tar file always has the actual man page. Our tool selection was based on what worked well with github and web page generation. -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Mon, Sep 26, 2016 at 03:19:53PM +0000, Hefty, Sean wrote: > > Infiniband-diags uses rst through rst2man. But if I had to do it over > > I would probably do it different. rst2man is not always installed and > > has caused build issues for some people. Whatever tool we use I would > > recommend it be something common. I'm not too familiar with markdown. > > Is this really common now? > > Only by those who want to provide actual documentation. Markdown is very popular on github and the integrated processing of the web UI is why I picked it for the docs I started. But rst started the trend of structued ascii.. IMHO, rst is more widely available in distros today than pandoc. rst2man is incredibly widely distributed: it comes with python-docutils which is widely included in every distribution. I have no idea why people would complain to you on that point. If something comes in-box in all the distros then it is fair game to depend upon, IMHO. > Libfabric uses a daemon that checks for updates to the markdown > pages. If it finds any, it generates the man page and commits those > changes to the source tree. So the tar file always has the actual > man page. Our tool selection was based on what worked well with > github and web page generation. I generally frown on checking in built files, but yeah, that is an option. Jason -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
> On Mon, Sep 26, 2016 at 03:19:53PM +0000, Hefty, Sean wrote: > > > Infiniband-diags uses rst through rst2man. But if I had to do it > > > over I would probably do it different. rst2man is not always > > > installed and has caused build issues for some people. Whatever > > > tool we use I would recommend it be something common. I'm not too > familiar with markdown. > > > Is this really common now? > > > > Only by those who want to provide actual documentation. > > Markdown is very popular on github and the integrated processing of the > web UI is why I picked it for the docs I started. But rst started the trend of > structued ascii.. > > IMHO, rst is more widely available in distros today than pandoc. > > rst2man is incredibly widely distributed: it comes with python-docutils which > is widely included in every distribution. I have no idea why people would > complain to you on that point. If something comes in-box in all the distros > then it is fair game to depend upon, IMHO. I thought so to. But python-docutils is in the "optional" section of RH. https://ask.openstack.org/en/question/67176/python-docutils-openstack-installation/ > > > Libfabric uses a daemon that checks for updates to the markdown pages. > > If it finds any, it generates the man page and commits those changes > > to the source tree. So the tar file always has the actual man page. > > Our tool selection was based on what worked well with github and web > > page generation. > > I generally frown on checking in built files, but yeah, that is an option. Yep I agree. But I resorted to this as well. :-( Ira -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Mon, Sep 26, 2016 at 06:17:03PM +0000, Weiny, Ira wrote: > > rst2man is incredibly widely distributed: it comes with python-docutils which > > is widely included in every distribution. I have no idea why people would > > complain to you on that point. If something comes in-box in all the distros > > then it is fair game to depend upon, IMHO. > > I thought so to. But python-docutils is in the "optional" section of RH. I mean it is available via 'yum' with no special repositories. I do not expect software to build out of the box on any arbitary distro install. I expect builders to install the required set of packages. This is why the exect package set is documented in the README.md Jason -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Mon, Sep 26, 2016 at 12:21:54PM -0600, Jason Gunthorpe wrote: > On Mon, Sep 26, 2016 at 06:17:03PM +0000, Weiny, Ira wrote: > > > > rst2man is incredibly widely distributed: it comes with python-docutils which > > > is widely included in every distribution. I have no idea why people would > > > complain to you on that point. If something comes in-box in all the distros > > > then it is fair game to depend upon, IMHO. > > > > I thought so to. But python-docutils is in the "optional" section of RH. > > I mean it is available via 'yum' with no special repositories. I do > not expect software to build out of the box on any arbitary distro > install. I expect builders to install the required set of > packages. This is why the exect package set is documented in the > README.md FWIW, I'm supportive of that. Just saying what my experience was. Ira -- To unsubscribe from this list: send the line "unsubscribe linux-rdma" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
diff --git a/buildlib/rdma_functions.cmake b/buildlib/rdma_functions.cmake index a4ecd7d4f2fe..260dd18d78df 100644 --- a/buildlib/rdma_functions.cmake +++ b/buildlib/rdma_functions.cmake @@ -135,8 +135,17 @@ endfunction() # filename function(rdma_man_pages) foreach(I ${ARGN}) - string(REGEX REPLACE "^.+[.](.+)$" "\\1" MAN_SECT ${I}) - install(FILES ${I} DESTINATION "${CMAKE_INSTALL_MANDIR}/man${MAN_SECT}/") + if ("${I}" MATCHES "\\.in$") + string(REGEX REPLACE "^.+[.](.+)\\.in$" "\\1" MAN_SECT "${I}") + string(REGEX REPLACE "^(.+)\\.in$" "\\1" BASE_NAME "${I}") + get_filename_component(BASE_NAME "${BASE_NAME}" NAME) + rdma_subst_install(FILES "${I}" + DESTINATION "${CMAKE_INSTALL_MANDIR}/man${MAN_SECT}/" + RENAME "${BASE_NAME}") + else() + string(REGEX REPLACE "^.+[.](.+)$" "\\1" MAN_SECT "${I}") + install(FILES "${I}" DESTINATION "${CMAKE_INSTALL_MANDIR}/man${MAN_SECT}/") + endif() endforeach() endfunction() diff --git a/librdmacm/man/CMakeLists.txt b/librdmacm/man/CMakeLists.txt index 791c98265ad0..d6cc106751a4 100644 --- a/librdmacm/man/CMakeLists.txt +++ b/librdmacm/man/CMakeLists.txt @@ -58,7 +58,7 @@ rdma_man_pages( riostream.1 rping.1 # FIXME: rsocket has a text substitution but nothing ever filled it in. - rsocket.7 + rsocket.7.in rstream.1 ucmatose.1 udaddy.1 diff --git a/librdmacm/man/rsocket.7 b/librdmacm/man/rsocket.7.in similarity index 97% rename from librdmacm/man/rsocket.7 rename to librdmacm/man/rsocket.7.in index dfb9804d849a..6adf156f4062 100644 --- a/librdmacm/man/rsocket.7 +++ b/librdmacm/man/rsocket.7.in @@ -129,7 +129,7 @@ fork off a process to handle the new connection. .P rsockets uses configuration files that give an administrator control over the default settings used by rsockets. Use files under -%sysconfig%/rdma/rsocket as shown: +@CMAKE_INSTALL_FULL_SYSCONFDIR@/rdma/rsocket as shown: .P .P mem_default - default size of receive buffer(s) @@ -149,7 +149,7 @@ polling_time - default number of microseconds to poll for data before waiting All configuration files should contain a single integer value. Values may be set by issuing a command similar to the following example. .P -echo 1000000 > /etc/rdma/rsocket/mem_default +echo 1000000 > @CMAKE_INSTALL_FULL_SYSCONFDIR@/rdma/rsocket/mem_default .P If configuration files are not available, rsockets uses internal defaults. Applications can override default values programmatically through the
rsocket.7 had an errant text substitution that never worked, it is a good idea to have the man pages use the correct paths, so let us have cmake run them through. Any man page ending in '.in' will be substituted automatically. Signed-off-by: Jason Gunthorpe <jgunthorpe@obsidianresearch.com> --- buildlib/rdma_functions.cmake | 13 +++++++++++-- librdmacm/man/CMakeLists.txt | 2 +- librdmacm/man/{rsocket.7 => rsocket.7.in} | 4 ++-- 3 files changed, 14 insertions(+), 5 deletions(-) rename librdmacm/man/{rsocket.7 => rsocket.7.in} (97%)