[cmake-developers] RST and documentation

[Stephen Kelly]

Hi,

We've had a while now to get used to the new docs system. Mostly I like it, 
though I haven't really looked much into what rst offers.

1) Indentation
Something that I liked about the previous system was that the output from 
cmake --help-* was indented. Can we indent the rst output too?

2) Compatibility
KDE relied on --help-custom-modules for creating a man page of the kde cmake 
modules. That does not work with CMake 3.0.0:

 http://quickgit.kde.org/?p=kdelibs.git&a=commitdiff&h=804d35394c366

I am left wondering why it would be difficult to process the existing (and 
very simple) markup in custom modules and generate rst on the fly for output 
from --help-module MyCustomModule and similar. Is there a reason not to 
restore compatibility like that? Otherwise any distro which upgrades to 
cmake 3 will lose those man pages in the KDE case, and probably similar in 
other cases. 

I think it would be best to avoid situations like distros packaging cmake 
2.8 and cmake 3.0, possibly renaming executables etc etc so that KDE4 and 
other packages can continue to rely on cmake 2.8. Restoring and keeping 
compatibility with issues like this would be important to prevent that.

3) Language documentation

I have a started a branch adding generic language documentation.

+Languages are enabled by the :command:`project` command. If no project 
command is in your CMakeLists file, one will be implicitly generated.
+
+By default the enabled languages are C and CXX. A special value of NONE can 
also be used to enable no languages.
+
+The :command:`enable_language` command can also be used to enable languages 
after the project command.

I'd also mention some language-specific variables (like 
CMAKE_CXX_COMPILER_LOADED) and language-relevant commands (such as 
target_compile_features whenever it gets in). Currently my branch adds that 
as a separate manual cmake-languages.7. That has far less content than most 
other manuals. Maybe if documentation about adding a new language were added 
it would be more justified. 

Or should such generic language documentation belong somewhere else, and not 
in a manual of its own?

4) Concept documentation

My intention was to work down a typical CMakeLists file to add conceptual 
documentation where it makes sense. 

* cmake_minumum_required/policies
* project/languages
* find_package/Find modules/Config modules
* build targets, various library types, target properties like PIC etc
* imported and other pseudo/special targets, and exporting them
* usage requirements
* cross-compiling/toolchain files etc.

Obviously, there are N ways one could split the above into M manuals. 

Any thoughts on how to do that? Group the build targets and psuedo targets 
together? Document the imported targets in the same manual as the Config 
modules? Document the usage requirements in the same manual as the build 
targets? Document the cross-compiling/toolchain items in the same manual as 
the language stuff?

What other concepts should be documented, as a goal?

Thanks,

Steve.