[cmake-developers] Converting CMake documentation to reStructuredText and Sphinx

[Brad King]

On 10/15/2013 11:06 AM, Eric Noulard wrote:
> 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.

My view of --help-$x-list is to get a list of names that I can give to
"--help-$x $name" to get the corresponding documentation.  This depends
only on available documents, not on the executable being run.  Clearly
the historical lack of complete implementation of this design has led
to help selection workflows never intended (though perhaps useful).

Instead we could introduce new APIs meant for command-line completion
or "tell me what this executable can run".  A number of approaches are
possible (structured markup used for filtering, explicit per-tool lists,
etc.).  They could interact with the domain directive markup indexing
discussed earlier in this thread.  We can discuss it further after the
initial transition.

> 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.

The new --help-manual option generalizes that approach.

-Brad