[cmake-developers] Please restore --help-full cmake option for version 3

Alan W. Irwin irwin at beluga.phys.uvic.ca
Thu Apr 24 14:42:20 EDT 2014

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 at raven> ~software/cmake/install-3.0.0-rc3/bin/cmake \
--help-manual cmake-commands |less

or the exactly equivalent

wine at raven> ~software/cmake/install-3.0.0-rc3/bin/cmake \
--help-commands |less

gives mostly equivalent results to

~software/cmake/install- \
--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 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

More information about the cmake-developers mailing list