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

[Eric Noulard]

2013/1/28 Brad King <brad.king at kitware.com>:
> 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.

If we transition from current doc format to rst (or may be asciidoc
see later on)
I'd suggest we keep a way to get command line doc from this new source.

My best wish workflow would be to write all docs in relatively powerful
but lightweight markup (like rst of asciidoc) and then

1) build-time generate "pure" ascii doc that can be parsed and spitted-out
    --help-xxxx  command line options like we have today.
    We could parse rst/asciidoc directly but it may bring more
dependencies into CMake
    source which doesn't seem a desirable property to me.

2) generate more beautiful doc (HTML, PDF/TEX/DOCBOOK)
    with links, references etc... with sphinx or whatever tool we chose.

1] is very important to me because:

   A) you keep sort of "builtin doc" with no needed tool
   B) bash/zsh completion works very well because of the --help-xxxx-list we
        have for cmake, cpack, ctest

> With this approach we could add new documentation sections just
> by adding .rst files to the source tree.

I insist that all "structured" doc should be accessible from command
line without
being forced to open a web browser or pdf viewer etc....

> Optionally we could use  something like Sphinx:
>
>  http://sphinx-doc.org/
>
> to build full documentation from them.

Sorry no time to go on IRC for some weeks I'll try to catch-up next week.
-- 
Erk
Le gouvernement représentatif n'est pas la démocratie --
http://www.le-message.org