[CMake] Documentation strategy

[Pau Garcia i Quiles]

Quoting "Alan W. Irwin" <irwin at beluga.phys.uvic.ca>:

I bought the book and it's worth every cent.

Once you know the basics of CMake, you can walk the way yourself but  
getting started with only the docs available in the website is wasting  
your time.

> On 2007-06-20 10:56-0400 Brandon Van Every wrote:
>
>> On 6/20/07, Philippe Fremy <phil at freehackers.org> wrote:
>>>
>>> All in all, CMake is a good and powerful tool, but I find that the
>>> documentation is lacking behind. More structure, more usage example,
>>> more common cases would in my opinion really help the user experience.
>>
>> Well, you can buy the "Mastering CMake" book.
>
> However, that is terribly out of date and paper so I have never been tempted
> to buy it. However, if a new edition of that book was made available in an
> open electronic format, I would be interested in using it and helping out
> with feedback if I discovered any problems with it. I have no interest in
> paper books any more, or closed electronic formats, but I do like to support
> electronic formats where you are free to do anything you like with them
> including copying to your friends to help popularize CMake. In the last few
> months, I have finally got off the dime and started using SVN for everything
> rather than continuing to limp along with CVS, and the subversion book
> (freely downloadable from http://svnbook.red-bean.com/ in a number of
> editions and translations) is a huge lifesaver, and I think it is one of the
> fundamental reasons why subversion is finally overcoming CVS's
> "first-to-market" advantage.  The analogy between subversion and CVS on the
> one hand, and CMake and autottools on the other is pretty good in the sense
> that you have outstanding new software that replaces the old, yet there is
> still a huge pool of people using the old software because of that old
> software's "first-to-market" advantage.  In sum, I think CMake could benefit
> a lot by following the model about how subversion is doing its
> documentation.  (Note, the subversion book also comes in paper formats
> through O'Reilly if you want to pay for those.)
>
>>
>> There's this strategic problem that modifying the CMake docs and
>> submitting patches for them is cumbersome.  The auto-doc structure is
>> fine for documenting individual functions, but it provides no
>> structure at all for general concepts encompassing many functions, or
>> CMake operative principles in general.  I haven't looked into whether
>> there's a good answer for this, although at some point I may.  It's a
>> basic infrastructure problem.
>
> Excellent point.
>
>>
>> I'm not sure wikis are the answer either.  I do add things to the
>> wiki, but I don't think wikis really cause a lot of people to make
>> significant doc contributions.  Then you run into the problem of "how
>> do we ship wiki docs?"  One answer is you don't, you force the user to
>> access the internet and use the - typically very limited - wiki format
>> for their lookup needs.  What people really want is docs that work
>> well with their chosen IDE.  In the Chicken Scheme community we've got
>> some people working on wiki --> TexInfo conversion, because they are
>> so irritated with all the docs being on a wiki.
>>
>> It seems like a really basic infrastructure common to a lot of open
>> source projects.  Reminds me of the motive for distributed rather than
>> centralized version control systems, like Darcs and Mercurial.  I
>> haven't looked around to see if anyone has come up with a better open
>> source doc paradigm.
>>
>
> Excellent points. I think of wikis as rough drafts of documentation so a
> wiki to "real" documentation language (TexInfo, docbook, or whatever)
> converter is a great idea. I was interested enough to do a google search for
> (wiki docbook conversion), and I particularly liked one suggestion I found
> which was to make software to convert wiki information into the APT (almost
> plain text) format, and then from that format you can convert into anything
> you like (see http://www.xmlmind.com/aptconvert.html).  I bet somebody has
> already made a rough Wiki to APT converter (which is all you would need),
> but I have not found it yet.
>
> Alan
> __________________________
> Alan W. Irwin
>
> Astronomical research affiliation with Department of Physics and Astronomy,
> University of Victoria (astrowww.phys.uvic.ca).
>
> Programming affiliations with the FreeEOS equation-of-state implementation
> for stellar interiors (freeeos.sf.net); PLplot scientific plotting software
> package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of
> Linux Links project (loll.sf.net); and the Linux Brochure Project
> (lbproject.sf.net).
> __________________________
>
> Linux-powered Science
> __________________________
> _______________________________________________
> CMake mailing list
> CMake at cmake.org
> http://www.cmake.org/mailman/listinfo/cmake



-- 
Pau Garcia i Quiles
http://www.elpauer.org
(Due to the amount of work, I usually need 10 days to answer)