2013/10/15 Brad King <brad.k...@kitware.com>:
> 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.
Ok right I miss-read the code.
>> - 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.
Ok right again. I see:
.. cmake:variable::
.. cmake:command::
> 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.
Yes right the dynamicity of the approach has a cost but you can do that
only when --help-xxx is invoked or build a new 'cdoc'
command that would include pre-parsed version of every *.rst file
in the CMake source tree.
If you read documentation you'll be opening probably a bunch of files
anyway so doing it with man, a web browser or cxxxx command does
not change much.
What should be avoided is to do this parsing when no doc at all is requested,
I had the remark when I contributed the cpack doc (may be from you if
I remember it well).
>> 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.
I disagree I think there is because:
1) cpack may be used without CMake
2) Many CMAKE_xxx variable have strictly no impact on cpack.
CMAKE_BUILD_TYPE, CMAKE_SKIP_INSTALL_ALL_DEPENDENCY,
CMAKE_INSTALL_PREFIX, ..
4) In the same way why would add_executable or add_test or
add_library appear in
cpack --help-command-list
3) Shell completion is very handy to get fast help, since they rely
on --help-XXXX-list it is faster to use if the list is as short
as necessary.
> 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 fact that CPack uses cmake scripts does not mean the cmake **command**
is processing the CPack scripts.
I'm sure you know that but cpack -G NSIS does not call cmake command,
it is simply creating a cmake script processing object instance.
In fact CPack is only using the the "cmake processing mode" commands so that
at least
cpack --help-command-list should exclude non-scripting mode CMake commands.
b.t.w. this is the case currently. Leaving that out would be a regression.
> 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.
ok just wanted to point out that builtin doc for variable, command,
property is quite good
and personnally I'd rather
$ cmake --help-command-list | grep add
or
$ cmake --help-variable-list | grep FLAGS
or
$ cpack --help-variable-list | grep NSIS | less
rather than browsing manual oriented doc.
When I'm looking for topic/concept oriented doc like "generator-expressions"
this is another story for which I would advocate the addition of
--help-concept as proposed by Stephen.
> 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.
You are the boss prioritizing the goal, I was just pointing out the fact
that having list and detail of variable, command, property
**on the command line** is very helpful to me.
My personal opinion though.
--
Erk
L'élection n'est pas la démocratie -- http://www.le-message.org
--
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
