Re: [boost] Copy editing documentation
I'm reading though the boost unit testing documentation at:
http://www.boost.org/libs/test/doc/components/utf/index.html
It's good, but I think could probably do with some basic copy editing. As I'm reading though it anyway I'd be happy to do it, is this ok? What procedure should I follow to do this?
I've alrady tried to do this, but failed because it is generated using Dreamweaver. Unless you have this software, and devise a CVS/SVN method of working togther with others, especially Gennadiy, it's difficult to work jointly. (This is why using Boost.Book aka Quickbook/Docbook is a more promising methodology)
Well, I've been asked to teach a short course on unit testing in C++. I might consider converting this in to DocBook format if it becomes useful for me. Btw, how widely is the Boost Unit testing library used? It seems that many libraries in Boost opt not to use it?
IMO, it is also the *structure* of the documentation that is causing most difficulty.
I'd be interested in hearing your views. As an aside could the class documentation not be generated directly from the source using something like Doxygen?
Nava Whiteford writes: [...]
Btw, how widely is the Boost Unit testing library used? It seems that many libraries in Boost opt not to use it?
Dunno how widely used, but we're using the heck out of it over here. (Company ~= 30 people, ~6 heavy C++ people, ~80k sloc highly mathematical C++ ). ---------------------------------------------------------------------- Dave Steffen, Ph.D. Disobey this command! Software Engineer IV - Douglas Hofstadter Numerica Corporation dg@steffen a@t numerica d@ot us (remove @'s to email me)
"Nava Whiteford" <nwhiteford@tchpc.tcd.ie> wrote in message news:Pine.LNX.4.44.0703081732010.24682-100000@vual.tchpc.tcd.ie...
I'd be interested in hearing your views. As an aside could the class documentation not be generated directly from the source using something like Doxygen?
I personally don't like docs produced using Doxygen (or similar). They still require considerable effort and in most cases look like reference rather than users guide/tutorial. Gennadiy
I'd be interested in hearing your views. As an aside could the class documentation not be generated directly from the source using something like Doxygen?
I personally don't like docs produced using Doxygen (or similar). They still require considerable effort and in most cases look like reference rather than users guide/tutorial.
Being in the thick of documentation right now, I think it would be a great SOC project to try to extend/adapt Doxygen to ameliorate these issues while preserving it's nice aspects. It would also be great to extend it so that code snippets can be directly inserted by name into the documentation (sort of like Knuth's WEB system in reverse) so that the code and dox stay in sync (this is one of the todos on the Doxygen web site already). That said, I like a lot of the aspects of Doxygen - better control over sectioning and pages and extended syntax for mainpage.h would be a great extension. Matthias
Matthias Schabel wrote:
I'd be interested in hearing your views. As an aside could the class documentation not be generated directly from the source using something like Doxygen? I personally don't like docs produced using Doxygen (or similar). They still require considerable effort and in most cases look like reference rather than users guide/tutorial.
Being in the thick of documentation right now, I think it would be a great SOC project to try to extend/adapt Doxygen to ameliorate these issues while preserving it's nice aspects. It would also be great to extend it so that code snippets can be directly inserted by name into the documentation (sort of like Knuth's WEB system in reverse) so that the code and dox stay in sync (this is one of the todos on the Doxygen web site already). That said, I like a lot of the aspects of Doxygen - better control over sectioning and pages and extended syntax for mainpage.h would be a great extension.
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect.
Two questions : 1) is there a good tutorial on using QuickBook? 2) does it support LaTeX markup? Matthias
Matthias Schabel wrote:
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect.
Two questions :
1) is there a good tutorial on using QuickBook?
Ehm, you don't really need a tutorial :-) Just read the docs. Anyway, the difficult part is having it installed. After that, all follows smoothly. The current docs has some sections on installation.
2) does it support LaTeX markup?
QuickBook outputs BoostBook which is a variant of DocBook. DocBook can output LaTeX. For PDF generation, one problem with the BoostBook tool chain is FOP which is incredibly buggy. John Maddock and I are investigating the alternate route from BoostBook to Latex to PDF. I invite you to join the Boost.Doc list to learn more and join in the discussion and possibly contribute some help :) Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
Ehm, you don't really need a tutorial :-) Just read the docs. Anyway, the difficult part is having it installed. After that, all follows smoothly. The current docs has some sections on installation.
Oh, that would be in the Boost CVS HEAD. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Joel de Guzman Sent: 08 March 2007 23:55 To: boost@lists.boost.org Subject: Re: [boost] Copy editing documentation - SOC project
Matthias Schabel wrote:
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect.
Two questions :
1) is there a good tutorial on using QuickBook?
Ehm, you don't really need a tutorial :-) Just read the docs. Anyway, the difficult part is having it installed. After that, all follows smoothly. The current docs has some sections on installation.
As a newbie using QuickBook, I agree with this - getting a working setup needed guidance and assistance, but once you are airborne, using it is pretty much of a doddle. html output works fine, pdf using free FOP is OK without pictures (and would be OK with SVG pics rather than jpegs), but if one can tolerate some discrete advertising, John Maddock has used a commercial package without much trouble. The advantage of also producing a pdf is that it can be printed, and that is can be searched using the Adobe Reader find. Being able to do this would have helped a lot of Boost.Test confusion. We could still use a better search (Googlish) tool. Quickbook 'language' is simple enough that we can expect the other tools to work better in time. IMO, the key advantage is that working collaboratively on files in the CVS sandbox, for example, worked smoothly. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
Paul A Bristow wrote:
As a newbie using QuickBook, I agree with this - getting a working setup needed guidance and assistance, but once you are airborne, using it is pretty much of a doddle.
html output works fine, pdf using free FOP is OK without pictures (and would be OK with SVG pics rather than jpegs), but if one can tolerate some discrete advertising, John Maddock has used a commercial package without much trouble. The advantage of also producing a pdf is that it can be printed, and that is can be searched using the Adobe Reader find. Being able to do this would have helped a lot of Boost.Test confusion. We could still use a better search (Googlish) tool.
Quickbook 'language' is simple enough that we can expect the other tools to work better in time.
IMO, the key advantage is that working collaboratively on files in the CVS sandbox, for example, worked smoothly.
Paul
--- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
I'm just a simple user / lurker at the moment (though I'm hopeful to be a contributor someday), but if Boost is moving to subversion would moving to Trac make sense? We have been using the wiki portion of Trac successfully to collaborate on documentation. Multiple engineers are able to contribute easily to content while having the ability to reference items in the repository, tickets and of course other wiki pages. There is an active community of Macro and Plugin authors providing features ranging from inline Graphviz support to News Flashes and enhanced image placement. Plug-ins such as CombineWiki allow you to produce html, pdf or postscript outputs. The conversion tools are a little raw right now; however, they are simply Python scripts that plug into the Trac framework and easily modified. Best Regards - Michael -- ---------------------------------- Michael Caisse Object Modeling Designs www.objectmodelingdesigns.com
on Sat Mar 10 2007, Michael Caisse <boost-AT-objectmodelingdesigns.com> wrote:
I'm just a simple user / lurker at the moment (though I'm hopeful to be a contributor someday), but if Boost is moving to subversion would moving to Trac make sense?
IMO Yes. I am currently running several Tracs. I love the integration of the wiki with the bug tracking system and SVN. I have set up an SVN post-commit hook (http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook) that lets you resolve and update tickets by writing things like Changed blah and foo to do this or that. Fixes #10 and #12, and refs #12. In subversion commit messages, which will close tickets #10 and #12, and add the commit message as a note to #12. If we had this kind of integration, maybe our bug trackers would get more attention than they do currently. -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Thu, 2007-03-15 at 17:03 -0400, David Abrahams wrote:
on Sat Mar 10 2007, Michael Caisse <boost-AT-objectmodelingdesigns.com> wrote:
I'm just a simple user / lurker at the moment (though I'm hopeful to be a contributor someday), but if Boost is moving to subversion would moving to Trac make sense?
IMO Yes.
I am currently running several Tracs. I love the integration of the wiki with the bug tracking system and SVN. I have set up an SVN post-commit hook (http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook) that lets you resolve and update tickets by writing things like
Changed blah and foo to do this or that. Fixes #10 and #12, and refs #12.
In subversion commit messages, which will close tickets #10 and #12, and add the commit message as a note to #12.
If we had this kind of integration, maybe our bug trackers would get more attention than they do currently.
GCC has this kind of integration with their patch manager, patches list, Subversion repository, and Bugzilla. It works *wonderfully*, because you can look up a bug in Bugzilla and get a link to the patch that fixes it, very easily. Cheers, Doug
I am currently running several Tracs. I love the integration of the wiki with the bug tracking system and SVN. I have set up an SVN post-commit hook
I don't know if you have considered other version control systems. I am succesfully using mercurial (hg) with the same integration with trac. I have found mercurial to be faster, easier to use, and more powerful than SVN. But I suppose, that is a whole other can of worms...
On Mar 15, 2007, at 8:07 PM, Hugo Duncan wrote:
I am currently running several Tracs. I love the integration of the wiki with the bug tracking system and SVN. I have set up an SVN post-commit hook
I don't know if you have considered other version control systems. I am succesfully using mercurial (hg) with the same integration with trac. I have found mercurial to be faster, easier to use, and more powerful than SVN.
But I suppose, that is a whole other can of worms...
It is a can of worms. We've already decided to go with Subversion, right after 1.34.0, and are not considering alternative version control systems, regardless of how interesting they may look now. Cheers, Doug
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect.
I have to say, as a non-CS person, I'm finding it hard to even keep track of the differences between DocBook, BoostBook, and QuickBook, much less figure out how to accomplish anything with them... Just as a side note, given that documentation is already generally regarded as one of the most painful parts of library development, I think it would be a good idea for Boost to standardize on one system or another and then provide a good tutorial on how to use it... For example, after browsing all the QuickBook documentation I could find, I still have no idea how to implement the code snippet import feature you described; furthermore, as far as I can tell, there is no .qbk source in Boost (from recent CVS-HEAD) that I could use to try to emulate your Spirit documentation (assuming that is the documentation that uses this reverse-lit import, which I can't know a priori). Finally, while there appears to be some way to have DocBook output LaTeX, it isn't clear to me that there is any way to have it parse and process LaTeX source in, for example, the way that Doxygen does so that you can get images of typeset equations in the HTML output. Maybe it's possible, but it is certainly far from obvious, and the amount of time I would have to invest learning a completely new system hardly seems to justify the potential benefit. Anyway, sorry for the rant - it just doesn't seem like this should be this painful... Matthias
Matthias Schabel wrote:
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect.
I have to say, as a non-CS person, I'm finding it hard to even keep track of the differences between DocBook, BoostBook, and QuickBook, much less figure out how to accomplish anything with them... Just as a side note, given that documentation is already generally regarded as one of the most painful parts of library development, I think it would be a good idea for Boost to standardize on one system or another and then provide a good tutorial on how to use it... For example, after browsing all the QuickBook documentation I could find, I still have no idea how to implement the code snippet import feature you described; furthermore, as far as I can tell, there is no .qbk source in Boost (from recent CVS-HEAD) that I could use to try to emulate your Spirit documentation (assuming that is the documentation that uses this reverse-lit import, which I can't know a priori).
Have you looked at the QuickBook documentation itself? It's in the Boost CVS HEAD at /tools/quickbook/index.html under section "Import". That feature is a fairly new addition. Oh, and Spirit does not use QuickBook. The docs predate QuickBook. Actually, the Spirit docs motivated its development. Finally,
while there appears to be some way to have DocBook output LaTeX, it isn't clear to me that there is any way to have it parse and process LaTeX source in, for example, the way that Doxygen does so that you can get images of typeset equations in the HTML output. Maybe it's possible, but it is certainly far from obvious, and the amount of time I would have to invest learning a completely new system hardly seems to justify the potential benefit. Anyway, sorry for the rant - it just doesn't seem like this should be this painful...
DocBook can output LaTEX but it cannot parse and process LaTeX source. There's a way to get MathML in, however. That avenue is being explored as we speak. You might want to take a look at http://dblatex.sourceforge.net/examples.html for example. That's the possibilities we are investigating on. I understand your rant perfectly. You do understand that we are first and foremost library writers and not really tool makers, right? That is why I keep on urging people to help in any way they can. The tools we use work, but they are far from perfect. There are only a handful of people actively participating in the doc tools department. We basically have a grasp on what needs to be done, yet, what we do lack is the needed time to actually implement them. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Have you looked at the QuickBook documentation itself? It's in the Boost CVS HEAD at /tools/quickbook/index.html under section "Import". That feature is a fairly new addition.
I hadn't found that - I'll check it out. Thanks.
DocBook can output LaTEX but it cannot parse and process LaTeX source. There's a way to get MathML in, however. That avenue is being explored as we speak. You might want to take a look at http://dblatex.sourceforge.net/examples.html for example. That's the possibilities we are investigating on.
It actually looks to me like dblatex does support parsing of LaTeX source, which would be a huge bonus...
I understand your rant perfectly. You do understand that we are first and foremost library writers and not really tool makers, right? That is why I keep on urging people to help in any way they can. The tools we use work, but they are far from perfect. There are only a handful of people actively participating in the doc tools department. We basically have a grasp on what needs to be done, yet, what we do lack is the needed time to actually implement them.
I do understand that there are challenges; as someone who is not really even a library writer, I'm not sure there is really anywhere that the small amount of time I might be able to contribute to such an effort would be beneficial given my minimal understanding of things like XML/XSLT/etc... I'm certainly happy to participate as a tester and provide input on design issues, though. Matthias
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: 08 March 2007 20:15 To: boost@lists.boost.org Subject: Re: [boost] Copy editing documentation
"Nava Whiteford" <nwhiteford@tchpc.tcd.ie> wrote in message news:Pine.LNX.4.44.0703081732010.24682-100000@vual.tchpc.tcd.ie...
I'd be interested in hearing your views. As an aside could the class documentation not be generated directly from the source using something like Doxygen?
I personally don't like docs produced using Doxygen (or similar). They still require considerable effort and in most cases look like reference rather than users guide/tutorial.
Strongly agree - OK for reference but using Doxygen usually deludes the programmer that he has done all he needs to - so there is no "How to /How do I ..." content. Most people 'get it' much for quickly from examples - and only occasionally need reference info. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
I've used doxygen with great results a la doc book. There is a section at the beginning of each file , @file, where you can put the usage examples, general documentation, rationales, etc. Most people think of doxygen as only the tags after each function... With a bit of patch and perl processing, it's used at Bloomberg to generate all the documentation, and it works great (when the documentation is well- written). There can be a few glitches, but the doc always reflects the actual code, and it makes editing the doc so much easier. However when it is unfinished, it is not pretty. That is perhaps the greatest disadvantage. -- Hervé Brönnimann hervebronnimann@mac.com On Mar 9, 2007, at 4:29 AM, Paul A Bristow wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: 08 March 2007 20:15 To: boost@lists.boost.org Subject: Re: [boost] Copy editing documentation
"Nava Whiteford" <nwhiteford@tchpc.tcd.ie> wrote in message news:Pine.LNX.4.44.0703081732010.24682-100000@vual.tchpc.tcd.ie...
I'd be interested in hearing your views. As an aside could the class documentation not be generated directly from the source using something like Doxygen?
I personally don't like docs produced using Doxygen (or similar). They still require considerable effort and in most cases look like reference rather than users guide/tutorial.
Strongly agree - OK for reference but using Doxygen usually deludes the programmer that he has done all he needs to - so there is no "How to /How do I ..." content. Most people 'get it' much for quickly from examples - and only occasionally need reference info.
Paul
--- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/ listinfo.cgi/boost
on Mon Mar 12 2007, Hervé Brönnimann <hervebronnimann-AT-mac.com> wrote:
There can be a few glitches, but the doc always reflects the actual code, and it makes editing the doc so much easier. However when it is unfinished, it is not pretty. That is perhaps the greatest disadvantage.
I'm not sure. If we could find an automated way to make sure half-baked docs were really, blatantly ugly, wouldn't it be a service to mankind? ;-) -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Mon, 12 Mar 2007 21:58:33 -0400 Hervé Brönnimann <hervebronnimann@mac.com> wrote:
I've used doxygen with great results a la doc book. There is a section at the beginning of each file , @file, where you can put the usage examples, general documentation, rationales, etc. Most people think of doxygen as only the tags after each function... With a bit of patch and perl processing, it's used at Bloomberg to generate all the documentation, and it works great (when the documentation is well-
written). There can be a few glitches, but the doc always reflects the actual code, and it makes editing the doc so much easier. However when it is unfinished, it is not pretty. That is perhaps the
greatest disadvantage.
Do you have a sample set of files that you can provide as examples of how to get doxygen to generate this information?
participants (12)
-
Dave Steffen -
David Abrahams -
Douglas Gregor -
Gennadiy Rozental -
Hervé Brönnimann -
Hugo Duncan -
Jody Hagins -
Joel de Guzman -
Matthias Schabel -
Michael Caisse -
Nava Whiteford -
Paul A Bristow