Hi,
First of all, I'm not sure if this is the right list for asking this kind of questions.
But I don't realy know where else to ask.
I'm working on a library, which I would like to submit to Boost. Formal review is
already
scheduled. The library I'm talking about is The String Algorithm Library.
My problem is, no wonder, the documentation. I have written some documentation several
months ago. Since then I have made several improvements to the library structure and
content, and the documentation gots obsolete. From various reasons, I'm planing a
complete rewrite.
Let's begin with a few words about the library.
Structure of the library is divided into several horizontal layers.
1.) Implementation layer.
Mostly in terms of functor classes, traits and policies
2.) Generic layer.
Generic plugable classes together with supporting utilities
3.) User-level layer.
Generaly forward to layer 2 for most common usage scenarious.
For example, imagine a replace algoritm. Its purpose is to replace a selected part of
sequence
with something else.
On the layer 3 it is represented for instance by a function 'replace_first( input,
what, format )'
It is suposed to replace first occurence of 'what' in the 'input' with 'format'.
On the layer 2 there is a generic 'replace( input, findF, formatF )'. This function
gets a parameter
'input' and two functors. 'findF' is suposed to find a match and 'formatF' will return
a subsitute
for this match. This layer also containes 'finders' ( used as findF ) and 'formatters'
( used as formatF ).
So 'replace_first' simply creates a 'first_finder' to look for 'what' and
'const_formatter' to replace
whatever it gets to 'format' and then if calls generic replace
Layer 1 is not important, because it container only implementation detail.
In the current documentation, only top-most layer is documented. However due to recent
changes,
layer 2 is quite usable and interesting too.
Now I'm getting to the real problem. I would like to document layer 2 in detail and
layer 1 only as a reference.
Together there is more than "150" functions to be documented. There are almost no
classes worth noticing just functions.
It is almost impossible to copy them into HTML and keep in sync with the code.
I have tried Doxygen to generate a documentation, but the results were very
unpleasant. Probably due to templated natute of
the whole lib, result was not very nice and readable.
I was following the discussion about BoostBook a little bit, and it seems to me that
it could be used for this documentation.
I have seen in the archives of this list that it is possible to generate a part of
documentation using doxygen and then
integrate it with BoostBook.
However, I don't really know where to start. I have no experience with DocBook at all.
I would be very greatful if somebody could help me started or at least give me some
hints how to.
Also any general-purpose documentation writing hints could be very helpful.
Thanks in advance
Pavol.
PS: Library in the current state can be found in the sandbox.
-------------------------------------------------------
This SF.Net email is sponsored by: INetU
Attention Web Developers & Consultants: Become An INetU Hosting Partner.
Refer Dedicated Servers. We Manage Them. You Get 10% Monthly Commission!
INetU Dedicated Managed Hosting http://www.inetu.net/partner/index.php
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
