openldap-devel December 2006

openldap-devel@openldap.org

11 participants
42 discussions

Re: Thoughts on doxygen for Devel Docs/API?
by Kurt D. Zeilenga 07 Dec '06

07 Dec '06

At 08:36 AM 12/7/2006, Gavin Henry wrote: >That one's obviously for the future, I concur that consideration on this one should be deferred. - Kurt

1 0

Re: Thoughts on doxygen for Devel Docs/API?
by Kurt D. Zeilenga 07 Dec '06

07 Dec '06

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

2 1

Re: [Please Authorise] Permission to use your glossary as a starting point for OpenLDAP docs addition?
by Kurt D. Zeilenga 07 Dec '06

07 Dec '06

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?

2 1

Updating monitoringslapd.sdf
by Gavin Henry 07 Dec '06

07 Dec '06

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/

3 4

Re: Documentation Roadmap
by Kurt D. Zeilenga 07 Dec '06

07 Dec '06

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

2 1

Re: [Please Authorise] Permission to use your glossary as a starting point for OpenLDAP docs addition?
by Kurt D. Zeilenga 07 Dec '06

07 Dec '06

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). Kurt

2 1

Re: Tables in SDF?
by Kurt D. Zeilenga 06 Dec '06

06 Dec '06

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/

1 0

[Please Authorise] Permission to use your glossary as a starting point for OpenLDAP docs addition?
by Gavin Henry 06 Dec '06

06 Dec '06

Dear all, I'd like to send this for a starter for a new glossary section. Am I allowed on behalf of the OpenLDAP team? Or do we want t start one from scratch? Thanks. --------------------- Hi, I'm heading up a doc team for OpenLDAP, and I was wondering if I could pinch your glossary as a starting point for a new glossary section? http://www.zytrax.com/books/ldap/apd/ Credits due, obviously ;-) 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/

1 0

Tables in SDF?
by Gavin Henry 06 Dec '06

06 Dec '06

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/

1 0

Thoughts on doxygen for Devel Docs/API?
by Gavin Henry 05 Dec '06

05 Dec '06

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. Thoughts? -- 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/

1 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

openldap-devel December 2006