[cmake-developers] organizing "concept" documentation (was: RST and documentation)

[Brad King]

On 11/18/2013 02:56 PM, Stephen Kelly wrote:
> 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.

This is really the start of several threads so I will branch out now.

> 3) Language documentation

Note there is now a "cmake-language.7" manual dedicated to the CMake
language itself (for CMakeLists.txt and .cmake files).  I'd prefer a
name for compiled languages that is distinct from this manual.

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

It is already a bullet in your list of concepts, and so should be
handled by the discussion below.

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

One nice thing about the new documentation system is that we can
organize things in many ways.  Even the manuals that enumerate
all the cmake domain objects (e.g. cmake-commands.7) can have other
sections.

> * cmake_minumum_required/policies

This can go in the introduction of the cmake-policies.7 manual page
and be linked from the cmake_minumum_required command.

> * project/languages
> * cross-compiling/toolchain files etc.

How about a "cmake-toolchains.7" manual for these two?
Or "cmake-build-toolchains.7"?  Other names?

> * find_package/Find modules/Config modules
> * imported and other pseudo/special targets, and exporting them

Create a "cmake-packages.7" manual that covers these.  It should
supersede the "CMake Packages" tutorials from the wiki:

 http://www.cmake.org/Wiki/CMake/Tutorials#CMake_Packages

You could port/cleanup/combine that information as sections of the
new cmake-packages.7 manual.  For example, the package registry page:

 http://www.cmake.org/Wiki/CMake/Tutorials/Package_Registry

can become a "Package Registry" section of the manual.

> * build targets, various library types, target properties like PIC etc
> * usage requirements

I think these all belong in a dedicated manual but I can't think of
a good name off the top of my head right now.

-Brad