> Synopsis has tunable comment processors - you can make them as smart or as
> dumb as you want them to be (it's Python, so it's easy ;-)). In my case,
> the rule is simple - the comment describing the function appears as a solid
> block right before its declaration with no intervening line separation.
Sorry I think I was unclear. I'm asking how a portion of that block
is devoted to a specific portion of the description. For example:
/** Brief description of function.
Long description of function
....
@return Describe the return value here.
@pre precondition for the function
@post postcondition for the function
*/
int f();
> > That's good to hear. It doesn't look like Synopsis has an
> > XML ouptput formatter yet -- is that in the works?
>
> It has a DocBook formatter, in fact... though it's being a little bit
> strange about type qualifiers at the moment. We just need to take a look at
> the differences with the HTML formatter to see what the major differences
> are.
Sounds like it's on the right track.
> > Also, as I recall
> > last time I checked on Synopsis I had installation issues or some
> > other difficulty -- that would have been shortly after the last
> > committee meeting.
>
> I think I can help with that. Anyway, since I've just wiped my machine I'm
> going to want to reinstall it myself, so we can experience the joys together
> ;-)
You first ;-)
> > Agreed, but I think in this case the diversity might be ok.
> > Document generation is sufficiently complex that I'm sure that
> > Synopsis and Doxygen will continue to have various strengths and
> > weaknesses that might draw some users to one or the other solution.
>
> They might, but as Doug has pointed out repeatedly, you won't be able to
> simply process regular C++ code and get reasonable BoostBook, so we'll have
> to add some new directives, markup formats, etc. That will be repeated work
> for us, on top of whatever differences the two tools have.
Well, you can get plenty of output from regular C++ but if you don't write
comments in the code in a structured way no solution is going to generate
a reference materials from the code, period. Either solution can generate
an unannotated header synopsis from pure C++, but that isn't going to cut
it for boost references. OTH, some people might want to take unannotated
source, generate a skeleton set of reference docs in XML from the source,
add meat to the generated XML and just maintain the XML.
As for repeated work, I don't think I follow. Doug has already written most
of the translation scripts for Doxygen XML output to BoostBook XML. For
Synopsis you could write a backend that just outputs BoostBook directly.
Or you could just use the Docbook directly and live with a slight reduction
in functionality. Anyway, once it is in BoostBook all the backend
processing is the same so I don't see that there is much overlapping work...
> I also think it's very likely that Synopsis will be an easier framework for
> that kind of project, due to its modular structure and the fact that it's
> written in Python... but I could be wrong about that. Haven't looked at
> Doxygen's code recently.
I have no plans to modify Doxygen personally, just feedback issues.
In that regard Synopsis should have a huge advantage if you feel
comfortable modifying it you can tune it to output boostbook
directly.
Jeff
-------------------------------------------------------
This SF.NET email is sponsored by:
SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See!
http://www.vasoftware.com
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
