Create man page as part of cmake build #181
Conversation
|
I'm trying to troubleshoot this PR... CMAkesLists.txt specifies cmake_minimum_required (VERSION 2.8), but it breaks with 3.1.1 because of the deprecated use of SOURCE in the add_custom_command. Since you know a lot more about Cmake than I do, can you suggest a workaround? I'm hacking at it now, but I might take all day... |
err no, am a complete muppet and copied the guru's (geoff) snippets in #177 and modified... Geoff wrote the code essentially, I only tweaks it.. ;-) |
|
That's okay, I keep learning a lot about cmake little by little. I'll merge this once I can get it working on 3.1.1. I see the other PR for dox, and I'll get to it in a bit, too. |
Create man page as part of cmake build
|
@pedromorgan, @balthisar, thanks for adding this... I did a test in my Ubuntu 14.04, and it worked fine... and tidy5.1 got added to the deb... Added a small tweak... all output should be kept to the 'build' folder, the so called CMAKE_BINARY_DIR, so it can be .gitignore'd, and not polute the source tree. And that would be true for any added cmake docs generation, so it also does NOT become part of the source. Preferrably into a sub-directory, like say Of course the needed components, like the tidy1.xsl, .cfg, etc have to be part of the source, BUT not any generated items... And as previously expressed hope these can soon be moved to says a 'docs' directory, or somewhere, but out of the build directory... Still to think on a window equivalent... any ideas appreciated... |
|
@geoffmcl said:
What a timely simultaneous posting. I requested a PR on the cmake_documentation branch for your code review. It moves documentation out of build, and only builds into a temp directory, and cleans up its temporary files. If you pull it, I can clean it up tomorrow and redirect the build to build/temp in instead of documentation/temp, as you're right: that makes a lot more sense. Also I wasn't able to test on Windows... I have a feeling it might break because some DOS commands aren't the same as Unix. |
|
@pedromorgan, @balthisar, just did an install test, and now think the line Seems cmake already adds the prefix As for windows there is no 'man' but as part of the SDK or MSVC there is a help file compiler, that if I remember correctly begins as a .rtf then uses something like a hcrtf.exe to convert to a winhelp .hlp file, but so long since I did this, need to re-discover the process... And will pull the branch for further testing soonest... but not sure why there is a PR and a branch... but will try to work it out ;=)) |
|
Re the destination
$ manpath
/usr/local/man:/usr/local/share/man:/usr/share/manSo
When I installed the deb here, the destination Maybe we an use |
|
Maybe be should be doing this in develop branch, so as not to break for users,, until we got it figured out |
|
@pedromorgan, that is strange that two linux cases do different install things! First, I did not use the deb to install it. I just used - And for some idiot reason can not get the deb generated at the moment... something not found and can't write some file... all too weird... it worked yesterday using But if you run - As stated with If you want to try And right at this moment to me master IS the development branch, as it usually should be... When we get to a 5.0.0 release, then it is my idea to create say a rel-5.0.0 branch, which people checkout if they want the last 'stable'. master is always the leading edge of develpment and should not garanteee anything... but we are not there yet... |
|
@pedromorgan, ok, got the deb to build... using cpack... just closed and re-opened a terminal??? This is using a modified CMakeLists.txt, with DESTINATION man/man1 $ dpkg -c tidy5....deb shows it will install in The cmake_install.cmake CLEARLY shows - Then a little later - So that means Now, on the other hand, if I alter the CMakeLists.txt to the absolute path `/usr/local/man/man1' then as I thought, cmake_install.cmake AND the DEB agree ;=)) as they should... But the cmake file adds a curious WARNING or ERROR if the user defines CMAKE_[WARN|ERROR]_ON_ABSOLUTE_INSTALL_DESTINATION? But I suppose we can ignore this... So maybe using Also note reading around that appearently Fedora uses And another titbit read during my searching and that is what package should be generated for what system... It said add
I will experiment in my cpack-test repo, which I suppose is where true 'experimentation' should take place... You can learn more every day ;=)) |
|
@pedromorgan, UGH, experimenting in cpack-test and reading some more seems you need to more or less write your own SystemSpecificInformations.cmake as it seems not part of the standard cmake distribution, so forget that last stuff! Let's just get the man page setup correctly... |
|
@geoffmcl, I'm fine with all of the suggestions. It was mostly an effort to get the documentation out of build/, and the learn a lot more about CMake. It quite literally took my entire day to make those changes. Overall it was worth it as it will never take that long again. We can avoid all of the xsltproc dependencies by reverting some of the changes that @pedromorgan introduced. There's no absolute need to include quickref.html in developer documentation, for example. For Unixes xsltproc is standard, or at least very easily installable. The typical user expects a man page, whereas on Windows a typical user has no such expectation for command line applications. I don't see a need to generate a Windows help file, either, because those are most often associated with GUI applications. From the strategy standpoint, is there any value in installing the quickref.html document at all? |
|
xsltproc is required to create the man page, so no xsltproc == no man or quickfref |
See issue
#177