Re: [cmake-developers] Please restore --help-full cmake option for version 3
On 04/24/2014 03:15 PM, Brad King wrote: > I had a work-in-progress topic left from back when I did the > documentation conversion to restore --help-full with index.rst > and add the Sphinx singlehtml option, but forgot about it. > I'm reviving it now. Restore --help-full option to output all help manuals http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=64f05923 Utilities/Sphinx: Add option to build 'singlehtml' format http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=faf291a9 -Brad -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Please restore --help-full cmake option for version 3
On 04/24/2014 03:01 PM, Matthew Woehlke wrote: > If there isn't currently a .rst file somewhere to concatenate all the > various documentation together with appropriate headings and table of > contents, this would probably be a good thing to add. (And then it could > be leveraged for --help-full.) Help/index.rst is exactly this. It's what generates the top-level help page for html. Our cmRST class we use to process .rst files for the --help options is capable of starting there and traversing the entire toctree. Also the Sphinx 'singlehtml' builder can be used to produce all documents in a single html file. I had a work-in-progress topic left from back when I did the documentation conversion to restore --help-full with index.rst and add the Sphinx singlehtml option, but forgot about it. I'm reviving it now. -Brad -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Please restore --help-full cmake option for version 3
On 2014-04-24 14:42, Alan W. Irwin wrote: So my remaining question (without all the html and man distractions) boils down to a request to implement --help-full as the concatanation (following the same order as the present CMake 2 results) of those individual manual results. Come to think of it, it's pretty common to have a monolithic form of otherwise categorized documentation. Single web pages are (as noted) much easier to search, likewise for man pages and plain text. And of course if you want the documentation in PDF form... If there isn't currently a .rst file somewhere to concatenate all the various documentation together with appropriate headings and table of contents, this would probably be a good thing to add. (And then it could be leveraged for --help-full.) -- Matthew -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Please restore --help-full cmake option for version 3
On 2014-04-24 08:56-0400 David Cole wrote: So even though the cmake binary can no longer generate the html and manpage documentation itself it is still available. To search the 3.0 rc4 help for find package, you can: http://www.cmake.org/cmake/help/v3.0/search.html?q=find+package That search (or typing both find and package in the search box) finds all instances of pages with both find and package (apparently), but you have to visit all those pages to see whether --find-package appears or not so I didn't bother since I was looking for a convenient method, and this search tool appears to not be that. So I tried using the search tool with various variants of --find (in quotes or not and with those -- characters escaped with "\" and uniform results were produced in all cases, i.e., zero hits. So it appears the -- characters completely confuse this search engine and there is no apparent way to escape them. Not good! And if you don't trust the web based search (or if it gives an extremely inconvenient and sometimes unreliable result like above if -- characters are involved) you can install the pre-built binaries for CMake, and grep down in the "doc/cmake-3.0/html" directory of the installation. That (or doing the equivalent with the man pages) is certainly possible, but it is obviously not particularly convenient either. I now do get it that the new CMake 3 documentation software produces html and man pages that can be installed so there is really no reason to make those accessible from the cmake command line. So that leaves the ascii documentation case that _is_ currently made accessible from the command line for the various manuals. So my remaining question (without all the html and man distractions) boils down to a request to implement --help-full as the concatanation (following the same order as the present CMake 2 results) of those individual manual results. It appears that many of the CMake 3 manuals are equivalent to prior CMake 2 results. For example, wine@raven> ~software/cmake/install-3.0.0-rc3/bin/cmake \ --help-manual cmake-commands |less or the exactly equivalent wine@raven> ~software/cmake/install-3.0.0-rc3/bin/cmake \ --help-commands |less gives mostly equivalent results to ~software/cmake/install-2.8.12.2/bin/cmake \ --help-commands |less and so forth for commands, modules, policies, properties, and variables. Of course, there are additional manuals for cmake 3 beyond those five most important ones. But establishing the appropriate order of all the concatanated manuals (obviously prepending just one of the command-line command manuals such as cmake, ccmake, etc.) to give a largely equivalent result to the cmake version 2 --help-full results for each CMake-related command-line command should be quite doable. In sum, access to concatanated ascii documentation with --help-full for CMake-2 for each different cmake-related command-line command allows knowledgable users superb and quick access to all documentation on the command line with regex search tools like "less" without fumbling around with unreliable html searches (see above) or a slew of different man pages. So having --help-full implemented for CMake-3 command-line commands in a similar way would be equally useful. Alan __ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); the Time Ephemerides project (timeephem.sf.net); PLplot scientific plotting software package (plplot.sf.net); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __ Linux-powered Science __ -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Please restore --help-full cmake option for version 3
On 24.04.2014 17:23, Matthew Woehlke wrote: Is there a reason CMake cannot know where to find these pages in order to display them on request? You mean have --help-man / --help-html output the distributed files? The new documentation (as distributed) is no longer single page so that would not map properly. (--help-man doesn't seem necessary except to generate the man pages; if they're being generated by some other means, I'd think 'man cmake' is sufficient to display them.) I think the same is true for the html documentation. The documented use case for both --help-man and --help-html is generating the documentation for the build rather than displaying it for the user. There may be undocumented valid use cases for regular users as well but I can't think of any. Nils -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Please restore --help-full cmake option for version 3
On 2014-04-24 08:35, Nils Gladitz wrote: On 04/24/2014 02:17 PM, Alan W. Irwin wrote: I also just discovered that --help-man and --help-html were gone as well for those who preferred man or html formatting of the full documentation as opposed to the ascii form delivered by --help-full. The latter is the most important to me and is presumably the easiest to implement, but I am sure others prefer the man page or html formats instead so I hope CMake developers will deal with those cases as well. The documentation is now generated by Sphinx (http://sphinx-doc.org/) rather than CMake itself. The man and html documentation (also "plain text" but not single file and not installed) can be generated when building CMake itself. The current html version of CMake git master e.g. looks like this: http://www.cmake.org/cmake/help/git-master/ So even though the cmake binary can no longer generate the html and manpage documentation itself it is still available. Is there a reason CMake cannot know where to find these pages in order to display them on request? (--help-man doesn't seem necessary except to generate the man pages; if they're being generated by some other means, I'd think 'man cmake' is sufficient to display them.) -- Matthew -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Please restore --help-full cmake option for version 3
> So even though the cmake binary can no longer generate the html and > manpage documentation itself it is still available. To search the 3.0 rc4 help for find package, you can: http://www.cmake.org/cmake/help/v3.0/search.html?q=find+package And if you don't trust the web based search, you can install the pre-built binaries for CMake, and grep down in the "doc/cmake-3.0/html" directory of the installation. "Just my opinion" always makes people smile or cringe. There's rarely a non-reaction... Glad you admired it and smiled this morning... ;-) HTH, David C. -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Please restore --help-full cmake option for version 3
On 04/24/2014 02:17 PM, Alan W. Irwin wrote: I also just discovered that --help-man and --help-html were gone as well for those who preferred man or html formatting of the full documentation as opposed to the ascii form delivered by --help-full. The latter is the most important to me and is presumably the easiest to implement, but I am sure others prefer the man page or html formats instead so I hope CMake developers will deal with those cases as well. The documentation is now generated by Sphinx (http://sphinx-doc.org/) rather than CMake itself. The man and html documentation (also "plain text" but not single file and not installed) can be generated when building CMake itself. The current html version of CMake git master e.g. looks like this: http://www.cmake.org/cmake/help/git-master/ So even though the cmake binary can no longer generate the html and manpage documentation itself it is still available. Nils -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Please restore --help-full cmake option for version 3
On 2014-04-24 04:38-0700 Alan W. Irwin wrote: So in sum, please restore the --help-full CMake 2 functionality (or an approximation to it where you simply dump out all documentation classes to stdout) for CMake-3. I also just discovered that --help-man and --help-html were gone as well for those who preferred man or html formatting of the full documentation as opposed to the ascii form delivered by --help-full. The latter is the most important to me and is presumably the easiest to implement, but I am sure others prefer the man page or html formats instead so I hope CMake developers will deal with those cases as well. And to adapt the polite but extremely useful "just my opinion" phrase from David Cole that I just admired ( :-) ) This suggested restoration of --help-full and the rest is just an expression of my (strong) opinion that cmake 3 should continue to be as convenient to run and use as cmake 2. Alan __ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); the Time Ephemerides project (timeephem.sf.net); PLplot scientific plotting software package (plplot.sf.net); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __ Linux-powered Science __ -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
[cmake-developers] Please restore --help-full cmake option for version 3
The --help-full CMake option (to dump essentially all classes of documentation available to stdout) is extremely useful at least on Unix where it can be pipelined to less and comprehensively searched with that application for whatever is relevant on a given topic using a simple phrase or more sophisticated regex expression. I just discovered that extremely useful --help-full functionality is missing for CMake 3 when trying to look up _all_ the relevant documentation on --find-package for CMake 3 to see whether that had changed from CMake 2. Here is the result with cmake-3.0.0-rc3. software@raven> ~/cmake/install-3.0.0-rc3/bin/cmake --help-full Warning: --help-full no longer supported That --find-package information is split into two parts so is in completely different kinds of documentation classes. Fortunately, --help-full gave me access to all documentation classes at once in a seachable way for CMake 2, but I had to try a lot of different versions of help commands to get access to both parts of the --find-package documentation for CMake 3. So the currently implemented large number of different ways to output different documentation classes for CMake 3 is useful for knowledgeable CMake users who are just double-checking something they already know pretty well. But for those who for whatever reason are not actually sure what documentation class they need or (as in the --find-package case) where the documentation is spread over two or more documentation classes, --help-full is really convenient for those familiar with the regex searching power of the less application. So in sum, please restore the --help-full CMake 2 functionality (or an approximation to it where you simply dump out all documentation classes to stdout) for CMake-3. Alan __ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); the Time Ephemerides project (timeephem.sf.net); PLplot scientific plotting software package (plplot.sf.net); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __ Linux-powered Science __ -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
