[CMake] Documentation suggestion

[Michael Wild]

How about extending the markup language with anchors and references,
e.g. like in AsciiDoc, restructuredText or MarkDown? E.g. using AsciiDoc
syntax:

[[if_cmd]]
Here goes the documentation for the IF() command.

[[else_cmd]]
See documentation of the <<if_cmd,IF() command>>.

When producing HTML, you simply transform the [[XXX]] into <a id="XXX"/>
elements and the <<XXX,text>> into <a href="#XXX">text</a>. For DocBook
output you set the id attribute of the following element and add a <link
linkend="XXX">text</link> element, respectively. For groff output, you
just keep the text of the reference and drop the anchor.

An issue is how to handle --help-command. Probably it would be
safest to simply not generate a link and use the text only.

Michael

On 05/02/2011 04:37 PM, David Cole wrote:
> Good suggestion.
> 
> We've also thought of that idea...
> 
> Here's what we need to implement it:
> 
> Do you have a good suggestion for how to represent links in the
> source code such that we can generated such linked documentation?
> 
> If it was easy, we would have done it already...
> 
> If you do have a suggested technology to use, we're all ears.
> 
> 
> :-) David C.
> 
> 
> On Sun, May 1, 2011 at 4:28 PM, David Doria <daviddoria at gmail.com>
> wrote:
> 
>> On this page: http://www.cmake.org/cmake/help/cmake-2-8-docs.html
>> 
>> there are many "See XYZ" statements. E.g.
>> 
>> ----- else: Starts the else portion of an if block.
>> 
>> else(expression)
>> 
>> See the if command. -----
>> 
>> It would be very helpful if these were linked to the anchor of
>> that command, e.g.:
>> 
>> See the [if] command.
>> 
>> David