Henrik, Thanks for taking the time to review all the docu. My comments are below, inline...
Le 30 oct. 2011 à 11:55, Henrik Ingo a écrit : > docs.drizzle.org > > So I see this is now committed to trunk, yet docs.drizzle.org still shows some > old documentation. What's the point of this? To me it seems some people really > went through a lot of trouble to keep Drizzle's capabilities a secret > from the wider > public: First they avoid documenting any of it, then they make sure > that if others > document something, it's not published... > > 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. > 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. > > Btw, this needs hacking the build system, but we should develop a system where > each plugin exports a default configuration into > /etc/drizzle/available-plugins/hello_world.conf > and to enable a plugin you symlink it to /etc/drizzle/conf.d/hello_world.conf > and then edit as needed. (This implies the plugin-add is part of its own > configuration file, not top level.) I'm not sure how this would, but a default config for plugins sounds reasonable. I would like, in the future, that plugins have a more unified "interface". For example, some plugins can be loaded but unless you also enable this or that, loading the plugin alone is useless. Or, some plugins like auth_file prevent Drizzle from starting if the default user file isn't in place or a new user file isn't specified. For example, I think plugins shouldn't prevent Drizzle from loading (except for fatal errors, of course). But that requires that plugins use dynamic options. Unfortunately, only query_log is truly fully dynamic. 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. > 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/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? > 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. > 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. > > - 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 :-( > > - 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... > > - 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. > 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/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. > 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. > docs/dirhtml/replication/drizzle/index.html > - Eh, you've moved this file, but apparently didn't actually edit it? > This looks like internals documentation to me, it doesn't explain how one > would actually setup replication. > - There should be a separate chapter on internals. Also a lot of Wiki stuff > needs to be moved there. No, I didn't edit anything about replication; I only moved it to its own directory in anticipation that someone will greatly expand replication topics, so replication-related files won't conflict with or clutter up the docs root dir. 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. -Daniel _______________________________________________ Mailing list: https://launchpad.net/~drizzle-discuss Post to : [email protected] Unsubscribe : https://launchpad.net/~drizzle-discuss More help : https://help.launchpad.net/ListHelp
