[cmake-developers] Adding some generic section to the docs ?

[Brad King]

On 01/28/2013 10:37 AM, David Cole wrote:
> Sure, it's independent, but the lack of that feature is a very strong reason why documentation HAS to be duplicated as things stand.

Yes.

> Attacking that problem first, and THEN de-duplicating documentation seems more logical to me.

I'd much rather migrate to an existing markup language like
reStructuredText than roll our own.  It will require additional
tools to be installed to build the documentation, but reST is
quite readable in source form anyway.

We can keep the current generated documentation internal markup
syntax and write a document formatter that produces .rst files
in order to transition while still allowing existing documentation
to work with command-line help output.

With this approach we could add new documentation sections just
by adding .rst files to the source tree.  Optionally we could use
something like Sphinx:

 http://sphinx-doc.org/

to build full documentation from them.

-Brad