Re: Thoughts on doxygen for Devel Docs/API?
by Kurt D. Zeilenga
At 12:48 PM 12/5/2006, Gavin Henry wrote:
>Hi All,
>
>What are your thoughts on using:
>
>http://www.stack.nl/~dimitri/doxygen/
>http://www.stack.nl/~dimitri/doxygen/docblocks.html
>
>I know a lot of OSS project use it, but not had any experience myself.
I cannot comment specifically on doxygen, but I can comment in
general.
The main problem in getting API documents, I think, is not
specific to whether such a tool is used or not. Though
use of these tools can help in the initial work of documenting
an API (and might produce value even in the absence of
documentation blocks), there main benefit comes in maintaining the API
documentation. That is, with or without the tool, we still
are faced with the problem that we have a huge pile of
undocumented code and documenting it won't be an easy task.
I think we need to be careful of taking on too many
documentation tasks at once. Personally, I rather our
documentation energy put into the Admin Guide and Manual
Pages first... but, hey, I'm not one to say "no" to those
willing and able to document OpenLDAP Software...
-- Kurt
16 years, 3 months
Re: [Please Authorise] Permission to use your glossary as a starting point for OpenLDAP docs addition?
by Kurt D. Zeilenga
At 01:23 AM 12/7/2006, Gavin Henry wrote:
><quote who="Kurt D. Zeilenga">
>> At 02:35 PM 12/6/2006, Gavin Henry wrote:
>>>Or do we want t start one from scratch?
>>
>> I rather start from set of terms in preamble.sdf and
>> http://www.openldap.org/faq/index.cgi?file=1390>. The
>> latter I just added (from a list I had created ages ago).
>
>
>OK, sure. So, how do we do tables? Can't see anything in the sdf docs.
See my response to your "Tables in SDF?" post.
>Also, the faq entry has lots of the same entries. copy and paste error?
Fixed.
>We obvoiusly need to expand on those, as RDN == "Relative Distinguished
>Name" doesn't really tell you much ;-)
How much do you want to tell? That is, do you want to provide
more than an overview of LDAP? That is, do you want to write
document discussing LDAP basics?
16 years, 3 months
Updating monitoringslapd.sdf
by Gavin Henry
Dear all,
I've just started to rewrite the whole of this section.
What's the best way to get all the explicit operational attributes you can
request?
I want to expand what you can get at via:
Backends
Connections
Databases
Listener
Log
Operations
Overlays
SASL
Statistics
Threads
Time
TLS
Waiters
I'm sure I've seen them mentioned somewhere.....
Thanks.
--
Kind Regards,
Gavin Henry.
Managing Director.
T +44 (0) 1224 279484
M +44 (0) 7930 323266
F +44 (0) 1224 824887
E ghenry(a)suretecsystems.com
Open Source. Open Solutions(tm).
http://www.suretecsystems.com/
16 years, 3 months
Re: Documentation Roadmap
by Kurt D. Zeilenga
At 01:09 PM 12/3/2006, Gavin Henry wrote:
>> and, more importantly, whether we want to produce and maintain one.
>
>This has been bugging me. I think we leave all the other projects to
>provide integration docs.
With LDAP clients, generally, yes. Our documents do however discuss
slapd(8) integration with Berkeley DB, OpenSSL, Cyrus SASL, Kerberos,
etc.. Of course, it's generally appropriate to assume the reader
is familiar with these packages. That is, we do try to avoid
duplication of documentation.
But discussion of how to configure/use particular non-OpenLDAP
LDAP clients is certainly far beyond the scope of the Admin
Guide
All client examples use OpenLDAP command line tools because a)
these are the only clients we can assume the admin has,
we need document our command line tools, and it should be
relatively straight forward to translate use of OpenLDAP
command line tools to other tools.
We do have a FAQ section titled "Integration"... where it
is considered fine to provide some discuss of other software.
>How about a Deployment guide instead, or would
>that fall under the Admin guide? The Deployment Guide could have real
>world cases etc. in it and the tuning/monitoring section.
Deployment of slapd(8), yes. Deployment of some particular
non-OpenLDAP software product, no. The information in the
admin guide should be generic, something which most everyone
can understand and make use of. Discussing slapd(8) administration
in terms of "white pages" is good because "white pages" is a
directory application that is simple in concept but also teases
out numerous directory service issues including authorization,
schema administration, tuning/monitoring, etc... and we can
generalize LDAP client issues.
>Lastly, what are your thoughts on a Wiki based system for rough TOC drafts
>etc. for new authors?
That's how I treat the FAQ... In fact, one of large documentation
TODOs should be adapt various FAQ into Admin Guide chapters.
For instance, much of the FAQ authorization answers should be
moved into the guide.
>Or should it be tracked on Devel FAQ and ITS for
>draft submissions?
Actual proposed changes to the Admin Guide, manual pages, and
other documentation distributed as part of OpenLDAP Software
are the same as OpenLDAP Software code. A patch against the
source should be submitted to the ITS system.
-- Kurt
16 years, 3 months
Re: Tables in SDF?
by Kurt D. Zeilenga
At 02:27 PM 12/6/2006, Gavin Henry wrote:
>Hi,
>
>How do you do tables in sdf? Trying to start a glossary.sdf
See http://search.cpan.org/src/IANC/sdf-2.001/doc/user/in_tb.html
There are a few examples in the Admin Guide. Just grep
for "block table".
But as there is already a set of terms defined in preamble.sdf,
best to use that to generate a glossary of terms.
See the newly committed glossary.sdf
Same can be done for references and products data sets.
-- Kurt
>Can't see any in the source.
>
>Thanks.
>
>--
>Kind Regards,
>
>Gavin Henry.
>Managing Director.
>
>T +44 (0) 1224 279484
>M +44 (0) 7930 323266
>F +44 (0) 1224 824887
>E ghenry(a)suretecsystems.com
>
>Open Source. Open Solutions(tm).
>
>http://www.suretecsystems.com/
16 years, 3 months
Tables in SDF?
by Gavin Henry
Hi,
How do you do tables in sdf? Trying to start a glossary.sdf
Can't see any in the source.
Thanks.
--
Kind Regards,
Gavin Henry.
Managing Director.
T +44 (0) 1224 279484
M +44 (0) 7930 323266
F +44 (0) 1224 824887
E ghenry(a)suretecsystems.com
Open Source. Open Solutions(tm).
http://www.suretecsystems.com/
16 years, 3 months
