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

[Eric Noulard]

2013/1/27 David Cole <dlrdave at aol.com>:
> On Jan 27, 2013, at 6:03 AM, Alexander Neundorf <neundorf at kde.org> wrote:
>
>> Hi,
>>
>> I'm about to start adding "Generic" sections to the generated documentation.
>> This could contain
>> * a section about the regeexps supported by cmake, so it doesn't have to be
>> documented in the string() and/or if() command
>>
>> * a section about generator expressions, this appars currently multiple times
>> in the docs
>>
>> * a section about the search order of find_xxx(), which appears currently
>> under find_library(), _file(), _path(), _program() and _package()
>>
>> Comments, objections ?
>>
>> Alex

[...]

> It would be nice to be able to cross reference the generic docs from the multiple places you are thinking of replacing... What's your plan for "see over here" type links?

+1

However, currently (at least from my understanding) links (in the HTML
or DocBook formatter)
are only created from within a section (see
cmDocumentationFormatter::ComputeSectionLinkPrefix and its usage)

Being able to cross-reference any existing section or command/variables outside
current section would be nice.
Since current documentation is somehow "free text" with some basic
rules for preformatted or list but without any markup. How would it be possible
to support [robust] links without markup and parsing magic headache?

Putting some links to previous discussions related to that subject:
  http://www.cmake.org/pipermail/cmake/2011-May/044138.html
  http://www.cmake.org/pipermail/cmake/2011-May/044171.html
  http://www.cmake.org/pipermail/cmake/2011-December/047948.html
  http://www.cmake.org/pipermail/cmake/2011-January/042349.html

And link to basic documentation of current "structured" text markup:
  http://www.cmake.org/Wiki/CMake_builtin_documentation_handling
Some discussion about doc when CPack documentation was introduced:
  http://public.kitware.com/Bug/view.php?id=10067

-- 
Erk
Le gouvernement représentatif n'est pas la démocratie --
http://www.le-message.org