[CMake] help texts

[Michael Wild]

On 12/08/2011 08:45 AM, Tom Deblauwe wrote:
> Hello,
> 
> 
> 
> I am trying to make a parser that can use  cmake --help-… commands
> to determine the functions that are available and their signature. I
> have 2 problems:
> 
> 
> 
> -          It is difficult to know if it’s an example usage or if it
> is the signature of the function

That's gonna be tough to detect automagically...

> 
> -          How can I know the keywords per function?
> 
> 
> 
> Now I just get the list of functions and then call cmake for each 
> function and parse the output lines where they start with the
> function name followed by a “(“ sign. Then this is the signature
> until an empty line or until a new function-name-with-“(“-sign is
> found.
> 
> Maybe the examples could be prefixed with something to distinguish
> them from the real function signatures? Maybe to solve the keywords
> problem the keywords could all be uppercase and the variables
> lowercase so I can extract them? This is in most cases correct now
> but e.g. in the “find_file” documentation there is “<VAR>” which
> would wrongly be extracted as a keyword.

If it's wrapped in <>, it is never a keyword.

IMHO the markup language used to document CMake is awfully deficient.
However, nobody has stepped up to improve it so far. My current
wish-list would be:

* cross-linking. Problem is, how to do it for text and manpages? Anchors
could be specified with [[name]] and [[name,label]] and referenced with
<<name>> or <<name,label>>. Care would need to be taken if the reference
points to somewhere outside of the current document (i.e. if the user
specified --help-command foo, and the docs for foo contain a reference
to bar).

* better formatting control (bold, underline, italics, typewriter). How
to represent these in plain text output? Is that even required, or can
we just skip it in that case? I'd propose *bold*, _underline_,
'emphasis' and `typewriter`. If the formatting is to span multiple
words, the markers are doubled, e.g. **bold words**.

* lists formatting. E.g:

  - bullet list
  * another bullet item
  ** nested bullet list
  *** deeply nested list

  . numbered list (arabic)
  1. numbered list (arabic)
  a. lower case alpha numbered list
  A. upper case alpha numbered list
  i) lower case roman numbered list
  I) upper case roman numbered list

* section titles. I would go for something like this:

  = Title
  == Sub-Title
  === Sub-Sub-Title

The level of the element would need to be automatically adjusted for
various outputs. E.g. the title of a command would need to become a
sub-title in --help-commands and a sub-sub-title in --help-full. Pretty
tricky stuff to get right.

* semantic instructions (e.g. to mark a block as being an example or a
command/function/macro signature). This could then be used in the
DocBook and HTML output. For this I would propose prefixing the block
with a [<block-type>] line, e.g. [example] or [synopsis]. In DocBook
output the would result in <informalexample> and <funcsynopsis>,
respectively. What other block types could be useful?

But as I said, this is my wish-list, not my todo-list ;-)

Michael