[cmake-developers] cmake --help output indentation (was: RST and documentation)

[Eric Noulard]

2013/11/21 Stephen Kelly <steveire at gmail.com>:
> Brad King wrote:
>> IMO the --help-* command-line options are
>> still present only for basic compatibility with pre-3.0 help and
>> should not be a focus of workflow enhancements.
>
> I don't consider --help-command an 'only compatibility' feature. It's the
> primary way I read cmake documentation.

+1
Same for me.
The same is true for --help-variable
for both CMake and CPack and was expecting the same thing for CTest.

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]

>From "my" point of view this is a great feature loss because:

I almost only use --help-xxx to get documentation.
I like the dynamicity of pre-doc-move CPack documentation dynamicity where
if you change your CPackXXXX.cmake module the command line doc gets
automatically
updated as well.

I think that Sphinx "batch processing" for browsable and indexed doc is great
but it does not means that the --help-xxx is made obsolete.

>> The output of the
>> individual domain objects is still pretty easy to use.
>
> By 'domain object', do you mean the individual .rst files? How would you
> read them without --help-command and without find+cat? How find+cat easier
> than --help-command?
>
>> All the
>> other output is just whole man pages which are better viewed with
>> real man page or html viewers.
>
> The --help-command option is much more convenient than
>
>  man cmake-commands
>  /find_package
>  n # enough times to get to the find_package docs, not references to it.
>
> It is also a disadvantage that the man context is not the command line
> context. Think of when you use cat or head instead of vi/less.
>
> Are you referring to something more convenient? I'm not a man page expert.
> There may be another way to get to the find_package docs than the above?

+1 again.
Not mentionning that if you have a shell with properly configured completion
you are **very efficiently accessing the doc** with

cma<tab>  --> cmake
cmake --help-co<TAB> --> cmake --help-command
cmake --help-command find_pac<TAB> --> cmake --help-command find_package

currently I can obtain (almost) the information

cmake --help-manual cmake-commands | less
/find_package$

You won't get other reference with the $ at the end.
Completion is more efficient because it is more tolerant to
typing error because you type less character.


I'd really like to have a command line tool with dynamic doc features.
If it's considered too costly for cmake/ctest/cpack then may be
I can try to craft a "cdoc" command line tool which can do just that.

Note that current sphinx generated documentation (I tested HTML)
contains "directive-defined" variable/command in the index only.

Utilities/Sphinx/html/genindex.html

you don't get any in:
Utilities/Sphinx/html/manual/cmake-variables.7.html
Utilities/Sphinx/html/manual/cmake-commands.7.html
nor in:
Utilities/Sphinx/html/commands/*
Utilities/Sphinx/html/variables/*

i.e. cpack_add_component is only there:
Utilities/Sphinx/html/module/CPackComponent.html#command:cpack_add_component
or CPACK_PROJECT_CONFIG_FILE only there:
Utilities/Sphinx/html/module/CPack.html#variable:CPACK_PROJECT_CONFIG_FILE

I would have expected those vars to appear in "commands" and "variables".

-- 
Erk
L'élection n'est pas la démocratie -- http://www.le-message.org