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 -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
