On 10/15/2013 05:57 AM, Eric Noulard wrote: > However, from my understanding of the "cmRST::ProcessModule" > assumes that all markup are in a "header" I think it would be more convenient > to allow "#.rst:" anywhere in a module
It is allowed anywhere in the module already. Any "#.rst:" line enables scanning of the immediately following comment block. > - interpret extra markup in order to decide whether if the > documentation is: > - a command > - a variable > - a property etc.... That's what the cmake domain directives do. They can appear anywhere in the documents. > Again, AFAIU you assume that "command" should be documented in > Help/command subdirectory, "property" in Help/property subdir. The CMake builtin (C++) commands and properties go there. Others can too if we want. > i.e. documentation category is built from Help/<dirname> > I don't think this is flexible enough and I'd rather use markup content > in order to do the classification. That's what the cmake domain directives do. The Help/<type> organization just saves the need to use the domain directives for everything explicitly. Look at the CPack module example for defining variables. They can be cross-referenced and are indexed in the html help just like the Help/<type> documents. The only part missing currently is that "--help-variable-list" and "--help-variable X" do not support directive-defined variables (and similarly for commands/macros/functions). This would be pretty expensive to support because we would have to scan all documents for variable definitions to produce the list. The fact that this works for CPack now is because there are only a small number of modules to scan. Some kind of pre-computed index would be needed. However, see the last paragraph of this message. > Moreover how do you decide which "*.rst" files are parsed for specific > c<command>? [snip] > how do filter out / include appropriate *.rst files? We don't. The cmake-commands.7 and cmake-variables.7 manuals are organized into sections accordingly. The toctree directives determine the organization. Each section leads with an explanation of when its content can be used (if only in the section name). In cases that the constraints are more granular the information should be in the item's individual documentation, or the manuals should be organized further. > In the current state of the source: > > cmake --help-variable CPACK_SET_DESTDIR works > whereas > cpack --help-variable CPACK_SET_DESTDIR does not. > > Do you want to settle so naming convention for the RST file like a > common prefix? No, we just need to teach ctest and cpack the same help options that cmake knows. There is no reason to exclude CPack variables from CMake help or vice versa. Any of the commands should be able to print any of the documentation. The cpack variables are meant for use in CMake code which are processed by the cmake tool anyway. The current state of the topic does the minimum necessary to reproduce existing help options as much as possible in the new system. Once we transition then new functionality can be added. However, I'd like to change the focus from cmake/ctest/cpack command-oriented organization to a manual-oriented organization. That will allow many more topics to be covered (like cmake-generator-expressions.7). Over time we can find new workflows for jumping to help at the command-line or elsewhere. -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
