[cmake-developers] Improving CPack Documentation (and may be others as well)

[Eric Noulard]

2012/1/24 Brad King <brad.king at kitware.com>:
> On 1/22/2012 7:58 AM, Eric Noulard wrote:
>>
>> 2012/1/3 Eric Noulard<eric.noulard at gmail.com>:
>>>
>>> back to cleaner way of work.
>>
>>
>> I did update and clean-up my previous attempt to ease documentation for
>> CPack.
>> http://public.kitware.com/Bug/view.php?id=10067
>
> Thanks for working on this.

I don't like writing doc but sometimes I'd like reading some
so may be the second needs the first... :-]

>> the new up-to-date branch is "stage/ImproveCPackDoc-reloaded"
>>
[...]

> I glanced through the changes and built the branch.  It looks okay
> to me.
>
> One nitpick I have is that the generated documentation adds extra
> blank lines between paragraphs:

Agreed...but...

> The markup parser needs to avoid adding the extra newline which tells
> the output formatter to start a new paragraph.

after 1 hour + reading & testing I'm now pretty sure
that the parser is not the cuprit...
(In fact I did avoid 1 extra line after the brief)

The cmDocumentationFormatterText should be....
in fact if you look at the output of:

cmake --help-module CPackComponent
or any other (untouched module)
cmake --help-module FindQt4

you'll see that the extra space are there as well.
So yes there is too much space, but this is not due to
my current proposal, it was there before.
We can handle that separately.

I won't be doing this now I'd rather agree on the new markup
feature first.

> Also I got an unused variable warning (-Wunused-variable) in
>  cmDocumentation::addCTestStandardDocSections
>
> during the build.

This one is fixed. I pushed the branch forward.
I fixed some prog. style and avoid an extra newline
just after the brief.


-- 
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org