On 11/21/2013 07:52 AM, Eric Noulard wrote: > On 2013/11/21, Stephen Kelly wrote: >> I don't consider --help-command an 'only compatibility' feature. It's the >> primary way I read cmake documentation. > > +1
Sorry, I didn't mean to imply that no one should use "--help-command". I meant the whole-manual viewers are minimal implementations that would not be there if we didn't have their help options before. I do not think it is worth trying to make the output of "--help-commands" as readable as Sphinx makes it. The primary command-line help options are the individual domain object ones ones like "--help-command list". I was saying that these forms print the help for just one object so they do not need indentation to distinguish the help from the object name section headings. > The same is true for --help-variable > for both CMake and CPack and was expecting the same thing for CTest. A lingering issue is that the CTest variables are not documented. When Help/variable/*.rst files are added for them then a section can be added to Help/manual/cmake-variables.7.rst to list them in a toctree. > I did already said that and Brad answered that: > > 1) He doesn't want to filter command/variable between CMake/CPack/CTest > > http://public.kitware.com/pipermail/cmake-developers/2013-October/008610.html > > http://public.kitware.com/pipermail/cmake-developers/2013-October/008615.html > > 2) He doesn't want to dynamically parse rst files so that > "directive-defined" variables > (or command) do not currently appear in --help-[variable|command][-list] At the end I said "We can discuss it further after the initial transition". I just didn't want to consider all that as a requirement to satisfy before transitioning. The perfect is the enemy of the good. Now that we have the new infrastructure in place we can look at extending it. That time is now. Most concerns about command-line help workflow raised in the thread up to this point can be addressed if we scan the .rst sources at build time to generate a pre-computed index of available builtin and directive-defined domain objects. The index can point back at the .rst files defining each object. That will allow the command-line help options to list and lookup everything efficiently. -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
