Hi Daniel Sorry it took some time to get back to this. I realized we need to file at least one bug because of this, and wanted to ensure I do that and not postpone it, so I left the entire reply waiting until I have time to focus. Below some comments.
On Wed, Nov 2, 2011 at 4:45 AM, Daniel Nichter <[email protected]> wrote: > FYI on a personal note in case anyone cares: I may not have any time in > November to make further contributions because my masters degree is very > demanding this time of year. > There is one thing that is easiest if you fix, I've reordered so it is here on top, and then there's a question second. Other than that, I can take the rest of the email and commit changes - enjoy your studies! >> docs/dirhtml/plugins/query_log/index.html >> - "Log queries that cause more than N errors." Errors or warnings? > > I don't know. :-) I'll have to look at the source code to remind myself > which session member function it's calling to get this value. > Please do, it's your code so it's easiest for you. >> docs/dirhtml/configuration/options/index.html ... > This is very important imho because non-dynamic plugins make Drizzle a pain > to administer because in real-world scenarios, the database server can't be > restarted. This is a good point. So far I have only developed plugins that don't take any options :-) >> docs/dirhtml/configuration/index.html >> - This will require some work, but we should script something that creates a >> page with a table of all options and variables, their types and default and >> allowed values. (Similar in spirit to >> http://dev.mysql.com/doc/refman/5.5/en/mysqld-option-tables.html) >> This is very Google friendly. > > I have such a script. It's what I used to generate the 70+ docs for each > plugin at first. But it's far from perfect because the plugins' code varies > widely, so it's really difficult to export such a list. I also wanted a > table, too, like MySQL docu has, but RST tables are poor imho because they're > really wide. This can be solved with some RST magic in conf.py I imagine. > Or maybe there's a way in RST to reduce the font size for certain text? > At least it could be a good start. Is that script perhaps shared in launchpad? ;-) Ultimately, perhaps the bzr repo could include a script that a plugin developer would run like: 1) ../generate_options_documentation.sh > docs/options.list.rst 2) manually edit docs/options.list.rst 3) at build time all plugin/*/docs/options.list.rst are combined together into a big list at docs/configuration/list_of_drizzle_options.rst Just as a rough idea. Anyway, I think it is reasonable to require that each plugin developer maintains this list under their docs/ directory. Possibly this could be the same list of options that is used also in the plugin docs/index.rst so that index.rst will include options.list.rst. Then we wouldn't add any documentation burden but it could still be easily included also into a common big list. *** For the rest we are either in agreement or things have fixed themselves. I can fix these via my lp:~hingo/drizzle/drizzle-docs71 branch. Except for the Authorization API limitation that I filed as a new bug, this email completes the review and I'll go ahead and commit the below fixes... > Le 30 oct. 2011 à 11:55, Henrik Ingo a écrit : >> The documentation committed to trunk should automatically be published on >> docs.drizzle.org > > I think docs.drizzle.org will need a new front page to make this viable. For > example, the current docu is for 7.0, i.e. the current GA. If we published > trunk's docu, that would be very confusing because, for example, 7.0 does not > have auth_schema. I think a new front page should let the user choose their > Drizzle version, much like http://docs.python.org/. There could be a link > for "Alpha" or "trunk" or whatever to let the user sneak-peek the docs in > trunk. > I've been pestering Brian and Patrick and perhaps some other innocent people too, but was able to catch mtaylor and MarkAtwood on irc last night. Turns out the idea was all along that whatever is committed to trunk is immediately published by a Jenkins job. (Trivia: docs.drizzle.org is in fact a Jenkins slave itself.) The reason it didn't happen was just that it was broken, but now it works again. Personally I think this is a good workflow. If you didn't want your stuff published, it should have been kept in some other branch until it is time to publish it. What is committed to trunk should always be usable. Now, your other point: I think a user of 7.0 (who btw are early adopters anyway) will probably benefit more from the documentation we've now worked on than the official 7.0 docs from last Spring. But going forward, should we have seprate manuals or not? MySQL does that. But in practice it is written in a way that the text always says in which version some feature was introduced. I find myself always reading the MySQL 5.5 manual even when using 5.1 server. PHP has only one manual and each page starts with specifying what versions it is valid for (http://fi.php.net/manual/en/reserved.variables.globals.php) I'd vote for doing it the PHP style. It is easier to maintain and to me it seems to work also when being a reader. For instance an immediate benefit is that reading the one-and-only manual you might realize you want to upgrade to get that new feature, whereas reading an old manual you would just not find out about the feature at all. All this being said, I also think docs.drizzle.org needs a new front page. We need to link to Doxygen docs which are again online: http://fi.php.net/manual/en/reserved.variables.globals.php Possibly we should also make a split so that there is a separate "book" on internals, for instance the replication chapter I complained about, stuff from the wiki, etc. I will take it upon me to think about a new front page at some point (unless somebody beats me to it of course, but it seems there are many final exams going on this November :-) So all in all, the front page should probably be a generic "welcome, you've found the Drizzle documentation" kind of page, which then links to various documentation resources, including the current manual which has to move away from the front page. I'll figure out how to do this. >> docs/dirhtml/administration/drizzled/index.html >> - I was cc'd off-list on an email from Patrick and Kent which says by default >> drizzle now writes to syslog. (Kent was channeling Brian.) >> Why these emails are not shared with everyone on drizzle-discuss is a >> mystery >> to me. > > I think this is a typo. Last time I looked, logging to queries was not > enabled by default, and it shouldn't be. Even query_log, when loaded, > doesn't start logging queries by default because I didn't want the plugin to > overload the server with a barrage of writes until the user was ready. This > works for query_log, though, because it can by turned on/off and configured > dynamically, whereas the syslog plugin cannot. > I think what Brian and Kent refer to is that the stuff drizzled normally outputs to stdout would now also go to syslog. Nothing from query_log of course, that would be crazy and lead to many swearing sysadmins. Will have to compile the new trunk and find out... >> docs/dirhtml/administration/authorization/index.html >> - Add sentence "Currently there is no plugin that would implement an >> authorization >> scheme using the standard GRANT and REVOKE keywords familiar from all other >> SQL databases. However, the internal authorization plugin API would fully >> support developing such a plugin, if someone wants to develop it." (Eh... >> I may have spoken to soon here :-( >> >> - Eh, is it true our Authorization API is just concerned about "access" and >> doesn't separate, for instance, reads and writes? > > I've wondered the same. I haven't see a method yet to make, for example, > read-only users. This is critically important imho. Filed a bug: https://bugs.launchpad.net/drizzle/+bug/887346 I'm sure either one of us will remember it when time comes to make 7.2 even better than 7.1 will be. The rest is just things we agree on and I've kept here as a reference for myself: >> docs/dirhtml/contributing/more_ways/index.html >> - link to actual donation page! >> https://co.clickandpledge.com/advanced/default.aspx?wid=46722 > > Yes, excellent idea. :-) > >> /docs/dirhtml/installing/requirements/index.html >> - this page smells old. Ubuntu 10.04 is tested but not 11.*? >> - The list of dependencies is suspiciously short. I've added >> dependency on libv8, you'd need to configure --without-js-plugin to >> avoid hitting an error without it installed. > > I didn't work on requirements (although I did rearrange Installing a bit). I > suspect you're correct though. > >> /docs/dirhtml/installing/ubuntu/index.html >> - When debs are made available, needs distinguishing between standard >> Ubuntu packages and newest from Drizzle PPA. >> >> docs/dirhtml/installing/redhat/index.html >> - Compiling from source is wrong, use yum build-depends (copy from README) >> >> docs/dirhtml/configuration/options/index.html >> >> I would put also this: >> plugin-remove=auth_all >> plugin-add=auth_file >> in the plugin specific config file (conf.d/auth_file.conf). That way >> if I remove >> the conf file, plugin is not loaded. Is there a reason why this shouldn't be >> used, recommended or does it even work? In any case, the example could use >> some >> truly drizzled lever options too, to make the point clearer. >> >> Many places, but for example docs/dirhtml/configuration/options/index.html >> - I disagree with using >> .. code-block:: bash >> for an interactive session such as using "drizzle". It makes words like >> "for" >> stand out highlighted. Only the first line in these code blocks is bash. > > I agree. > >> docs/dirhtml/administration/authentication/index.html >> - "there are no grant or privilege tables." Not quite true, since a plugin >> could define some. What you are trying to say is that "by default there is >> no single source where users are defined, such as a system user table, but >> each authentication plugin will use different sources to verify the >> usernames >> and passwords. (The plugin auth_schema does however keep users in a table >> inside Drizzle, much like the familiar MySQL way of authenticating >> users works.)" > > True. This should be clarified in the docs. > >> - LDAP authentication can use the mysql protocol if you create the >> drizzlePassword field and populate it with a hashed password. Edward (koko) >> is writing the documentation on this. >> >> - Don't be shy here. In the third paragraph you should add a sentence saying >> something like "If you are unsure what to do, you should enable the >> auth_schema >> plugin as this is the simplest yet secure method to enable user >> authentication. >> See the auth_schema documentation for details." >> >> - Instead of just linking to each plugin, it would give a nice overview to >> have >> a short description of each. Example: >> PAM Authentication allows you to connect to Drizzle using your Linux >> username >> and password. > > Yes, a short description would be nice.. > >> docs/dirhtml/administration/authorization/index.html >> - "there are no grant or privilege tables." Same comment here. >> >> - This is a comment on the auth_regex plugin implementation: The pair of >> commands ACCEPT/DENY is confusing. It should have been either ACCEPT/REJECT >> (see iptables) or ALLOW/DENY (see apache httpd). Possibly I will >> file a bug, possibly not... >> > I might actually just change this myself to support ALLOW/DENY and deprecate the original ACCEPT/DENY but still support it. >> docs/dirhtml/administration/logging/index.html >> - Same here, need to check if syslog is in fact enabled by default now. >> >> - The text already links to various plugins, but perhaps add a list at the >> end with all logging plugins in alphabetical order (or preferred order?). >> >> docs/dirhtml/administration/plugins/index.html >> - How did you come up with the list of default plugins? At least JS is >> missing. > > At first I looked at drizzled --help, then drizzled/module/load_list.h, but > then I figured the real list is in DATA_DICTIONARY.MODULES, so that's my > source and the list is still incomplete. It seems that drizzled --help is > far from complete because D_D.MODULES shows a much longer list. > Ok, will make sure to update based on D_D.MODULES. henrik -- [email protected] +358-40-8211286 skype: henrik.ingo irc: hingo www.openlife.cc My LinkedIn profile: http://www.linkedin.com/profile/view?id=9522559 _______________________________________________ Mailing list: https://launchpad.net/~drizzle-discuss Post to : [email protected] Unsubscribe : https://launchpad.net/~drizzle-discuss More help : https://help.launchpad.net/ListHelp
