Re: Patch for documentation

For the records, here's the log of today's discussion on #php.doc: <stefanSUN> So let's get started ... <stefanSUN> The whole discussion started with us (= MySQL Docs) syncing the PHP docs over to http://dev.mysql.com/doc/refman/5.1/en/php.html <stefanSUN> And announcing it, and announcing that we'll take "ownership" of those docs <bjori> hmh. give me a minute then to quickly browse it, never seen that before <stefanSUN> bjori: It doesn't differ from the docs on php.net. The only difference is that we've added a license notice to each page. <bjori> ahh, misread "syncing the php docs over to" to "from mysql.com to php.net" .) <stefanSUN> OMG, no :) <bjori> ok ok <stefanSUN> bjori: What we'll do is edit the docs *on php.net*, through CVS <bjori> which is great, but the current structure of the docs is confusing <stefanSUN> We'll also automate the syncing process which is currently manual <bjori> lot of mysqli_foo_bar() functions randomly map to class properties or methods <MC|Sun> Automated is just a crontab line :) <stefanSUN> docs as in "the ext/mysql etc. stuff on php.net"? <bjori> and the naming scheme varies from mysql_function() mapping to $mysqli->function() to $mysqli_result->function() <bjori> s/mysql_function/mysqli_function/ <stefanSUN> bjori: So you're suggesting ext/mysql and ext/mysqli docs should have the same structure? <johannes_> stefanSUN: no mysqli has two interfaces, procedural and object oriented and they are a bit messed up from the doc structure <bjori> since ext/mysql doesn't have an oo interface it can't be the _same_ <johannes_> (oh, and sometimes probasbly from the API structure) <MC|Sun> There are a bit messed up API wise - the docs just follow the real structure <bjori> take http://no.php.net/manual/en/class.harudoc.php for instance. thats an oo extension which every class has its own reference page and all of its methods has its own refentry as a child of its class reference <stefanSUN> bjori: Okay, but you're suggesting *similar*, right? <MC|Sun> We can't easily do anything about the fact that the method and class names don't always match unless someone changes the code <bjori> the problem for mysqli is that it has two interfaces, procedural and oo.. that wouldn't be a problem if there was a one-to-one mapping from classname_methodname() to $classname->methodname().. but it isn't <bjori> I'm suggesting similar to the haru structure (which is the currently deployed structure for mysqli) <bjori> but there are so redicilously many edgecases in mysqli mapping that its not working very well <stefanSUN> Sure, but as MC says there's nothing we (Docs) can do about it. <bjori> so... we obviously can't rename functions to be consistent to classname_methdoname().. but we can maybe come up with a better way to browse the precodural interface without duplicating the method docs... * andrey hat die Verbindung getrennt (hub.uk efnet.demon.co.uk) <bjori> currently we document the methodname/property on the same page as the procedural function (multiple <refname>s) <bjori> and thats fine, as long as you are looking for the oo way of doing things <stefanSUN> So you're suggesting to separate OO from procedural? <bjori> I don't know what I'm suggesting. my initial suggestion was how it is now <bjori> however, if I am looking for mysqli_fetch_lengths().. I can I find it in the current doc? <bjori> there is no mysqli_fetch class, so I'd assume its a part of the mysqli class.. which it isn't <bjori> and there comes the problem <bjori> how can we make both the oo interface and procedural interface readable? <stefanSUN> bjori: What about adding an overview table with everything, regardless of class or not <stefanSUN> ? <bjori> we had that ones, and that page was huuuuuge <stefanSUN> Sure <bjori> impossible to find something on it unless you knew the exact name of the thing you were looking for <stefanSUN> Well, STRG+F is your friend <stefanSUN> See http://dev.mysql.com/doc/refman/5.1/en/func-op-summary-ref.html <bjori> if you know the exact name of it yes <bjori> but if you don't then your screwed <bjori> which is why we try to categorize it by classnames <stefanSUN> No, there's a second column indicating the usage <bjori> http://web.archive.org/web/20070426100158/http://www.php.net/manual/en/ref.mysqli.php <stefanSUN> If the world had gone OO we wouldn't have that discussion I guess ;-) <stefanSUN> Okay, that's similar to what I was suggesting <bjori> and this is what people didn't like so it was upgraded to http://no2.php.net/manual/en/class.mysqli.php * felipe_ (~felipe@ns.fioprev.org.br) hat #php.doc betreten <bjori> http://no2.php.net/manual/en/ref.mysqli.php and this is my favorite <bjori> I had no frcking clue what all that stuff was <bjori> so. how can we group the functions/methods/properties in a readable manners both for the oo interface and the procedural one? <stefanSUN> Two pages? * andrey_ (~nix@androto.ddns.playtime.bg) hat #php.doc betreten <stefanSUN> Two overview pages, I mean <bjori> and still document mapped method/function/property together, just with two overviews, one as it is currently and antoher only listing functions? <stefanSUN> Has pros and cons :) <bjori> indeed <stefanSUN> The cons are stronger I think <bjori> I'm open for everything <stefanSUN> The con of completely separating procedural from OO is mostly redundancy <bjori> and it'll make the user think "maybe there is no oo variant of this function" and vice-verca <stefanSUN> Which we could easily fix by storing stuff in Dynamic Docs. Well, probably not easily, but we could :-) <stefanSUN> Well, my take at that is that, as a developer, you're either procedural or OO, never both at the same time. <bjori> what exactly is this "dynamic docs"? I didn't quite understand what it was when I quickly browsed it; it looked just like regular docbook 4.3 <stefanSUN> It's a home-grown XML format, very much database-like <MC|Sun> It generates docbook, the clever stuff is what builds that in the first place <stefanSUN> Unlike DocBook <bjori> you wouldn't belive how many times I've seen $mysqli = new mysqli(...); mysql_query($mysqli, "SELECT * FROM foobar"); <stefanSUN> bjori: I know I know. I've done that, too, because I'm not a developer but rather an interested layman :) <bjori> :P <bjori> so.. using that dynamic docs stuff, what would it do that a pure docbook wouldn't solve? <stefanSUN> But mixing procedural and OO in the docs is what will drive many people into coding like this <stefanSUN> The main advantage is that it keeps the information in one place <MC|Sun> It would enalbe us to keep the definitions in one place, but to generate both the OO and procedural output <bjori> "pure docbook" == docbook+xinclude+xpath+... <bjori> ok <stefanSUN> "Controlled redundancy", sort of <bjori> hehe <stefanSUN> The problem with xinclude etc. is that you can't have section IDs twice in a document. With Dynamic Docs, you sort of can. <stefanSUN> Also, it's much less messy <MC|Sun> And much more flexible <bjori> ok <andrey_> .oO(this got too much into technology :) <stefanSUN> Question is if Dynamic Docs would jive with the PHP docs way of handling things <stefanSUN> andrey_: You're not that techy kind of guy, are you? ;-) <bjori> but that would duplicate the entire docs and not show the mappings of functions<->oo (in case I would want to see how the oo way of doing "mysqli_free_result()" would be) * andrey_ is not that doc-techy <stefanSUN> I think we could fairly easily add that mapping in Dynamic Docs <stefanSUN> MC|Sun: What's your take? <MC|Sun> It's just an output format - I can get the DynamicDocs to produce whatever we want <stefanSUN> Guys, I need to run in about 5 minutes. Can I leave the Dynamic Docs discussion to you? <MC|Sun> If we did this, I would suggest DynDocs to generate PHP Docs files directly, then we can sync the PHP docs over to MySQL like we do now <stefanSUN> The disadvantage (for us at MySQL) is that we'd have to help set up things on php.net, right? <stefanSUN> After all, Dynamic Docs is more than just a Perl script <bjori> and teach anyone that is interesting in modifying/fixing bugs in the docs the syntax <bjori> and let everyone know that the docbook files are autogenerated and they should not be touched <MC|Sun> Hmmm...you could just generate the docbook files and import to php - and not worry about actually generating the files within the PHP docs system <stefanSUN> bjori: Right, but I'd consider that a minor disadvantage, since no one seems to be interested in editing the ext/mysql* docs, anyway. <bjori> anyway, I think we are little ahead of ourselfs. first thing first: how exactly do we want the structure? <bjori> stefanSUN: I spent a whole day on them... <bjori> and I don't even use the extension <bjori> (no offence :) <stefanSUN> bjori: 2 overview pages, OO/procedural separated, and a mapping of some kind that shows relationships of OO/procedural. <stefanSUN> That's my suggestion :) <MC|Sun> There's no reason in the new mysql docs structure the PHP dynamic docs couldn't be a separate repo that we can control access to <bjori> MC|Sun: what if a phpdoc guy edits the committed docbook - how would you sync that to "dynamic docs"? <MC|Sun> We couldn't <stefanSUN> MC|Sun: I'm not sure if the PHP guys would be happy with losing control over some part of *their* docs. <bjori> so when the docs are regenerated after you guys make changes to the dynamic docs the changes by the phpdoc person are lost <MC|Sun> Then DynDocs isn't an easy option <stefanSUN> Exactly <stefanSUN> MC|Sun: Except if we'd implement the whole thing on php.net <stefanSUN> Which might not be an option either <stefanSUN> Anyway, got to run. <stefanSUN> Please send the log (or the link to the log) of this discussion! <stefanSUN> Thx! * Du bist jetzt bekannt als stefan|aw <stefan|aw> aw = away :) <MC|Sun> Putting DynDocs into phpdoc would not be an easy solution <bjori> if its the best option then you guys do have a guy paid for doing it - I'm sure he can handle some difficulties ;) <stefan|aw> bjori: We could ask if anyone at PHP would object against losing *some* control by us putting stuff in Dynamic Docs. <stefan|aw> Okay, but now I'm gone, really <bjori> what happens then in 3years? <bjori> noone knows how the mysqli docs are generated and people have started to change the docbook files.. needing to commit the exact same change to two files <bjori> but forgetting the latter file - then somone comes around and does some changes to the latter file.. forgetting the previous files <bjori> then we wind up with two idently functions/methods with two completely docs <bjori> missing a lot of words there *sigh* <bjori> then we wind up with two identical functions/methods with two completely different docs <MC|Sun> Let's ignore dyndocs for the moment and concentrate on the structure. <bjori> and then someone at mysqli finds this docbook creatation script and runs it.. nuking all the changes made of the docbook files <bjori> MC|Sun: fair enough <MC|Sun> If the structure looks like it warrants some additional method, we can worry about that later; probably a modified PhD might actually be able to do what we want anyway <bjori> true <bjori> the idea so far is a "mashup" of http://no2.php.net/manual/en/class.mysqli.php and http://web.archive.org/web/20070426100158/http://www.php.net/manual/en/ref.mysqli.php (minus the class listing) <MC|Sun> I'm just trying to read back a second as I've been in another meeting, one second <MC|Sun> Hmm, ok <bjori> actually. only the "table of contents" from the web.archive.org link plus the current docs <MC|Sun> Do you mean the other way round? <bjori> visually, the otherway around yes <MC|Sun> I don't see much difference (beyond spacing) than the TOC on the current link and the old one, except maybe the better differentiation of properties and methods <bjori> so, on the left table of contents (http://no.php.net/manual/en/class.mysqli.php) there would be a link to "all functions", which would list all the functions <MC|Sun> Right <bjori> what to do with the "aliases and deprecated mysqli functions" stuff? <bjori> thats a horrible name, and very weird <MC|Sun> Either we delete, or include a 'Deprecated Interfaces' section <bjori> ok <MC|Sun> So, we are looking at: <bjori> then moving on the class reference pages. should those list all methods (including aliases) and properties (including properties that have getters)? <MC|Sun> 1) Promoting the OO interface first <MC|Sun> 2) Making functions an 'additional way', rather than a recommend way <MC|Sun> ? <bjori> yes <MC|Sun> OK <MC|Sun> Then, yes, we need all method,s aliases and properties on those pages <bjori> in theory it should be logical enough the user would know which method a class belongs to <bjori> ok <bjori> then viewing a property doc, should that show me the getter methods and the function mapping to? <bjori> and if so, in the see also or in the <refname>s? <MC|Sun> Yes, I think so <MC|Sun> Well, see also would have to imply they were separately referenced <MC|Sun> Do we want to go that deep? <bjori> preferably not, cause that implies duplicated content and extra "what if" confusing for the end-user <MC|Sun> Right, so refname's are better, providing we can keep it clear <bjori> so.. keep everything as-is, only adding a function listing page? <MC|Sun> One second, just reviewing the other bits <MC|Sun> That seems like little to change <MC|Sun> Surely it can't be that simple? <bjori> no idea. I haven't identified all the weird function<->method<->property mappings so I don't know how easy it would be to find what I'm looking for <bjori> but the biggest problem in the current way: php.net/mysqli_fetch_field doesn't work <bjori> php.net/mysqli_result_fetch_field does however <MC|Sun> Not here - bot take me to the fuinction list page <bjori> http://no2.php.net/mysqli_result_fetch_field <MC|Sun> Ah <MC|Sun> Hmmm - no both of those worked for me * MC|Sun tries again <bjori> http://no2.php.net/mysqli_current_field then <bjori> (the property name) <MC|Sun> But that's because that isn't an ID though, right? <bjori> anyway. the errorhandler only searches the IDs, not the refnames (which it should, but PhD isn't smart enough yet - and not all mirrors use sqlite yet..) which means that the shortcuts don't work for both method, property and function mappings <bjori> I did commit a diiiiirty workaround for some mysqli functions/properties to workaround this issue to the error handler, but that doesn't cover all the cases - and the only way to do that is to list them all <bjori> which is stupid <bjori> not to mention annoying work to maintain and shouldn't be needed anyway (no other extension needs any special treatments in the error handler) <MC|Sun> So what is required to fix that? <MC|Sun> Is that a docbook formatting issue, or a PhD one? <bjori> PhD really <bjori> the PhD indexer should be smart and save stuff to sqlite database which we can use on the mirrors <bjori> I think the curernt PHD_ENTERPRISE branch has a realatively smart indexer <bjori> which probably solves the shortcut issue - but that branch still has a "lot" of work to be done <MC|Sun> OK, so where does that leave us on the docs? <MC|Sun> Should we be building a sample layout and then working out how to make that happen? <bjori> I think that would be the best course of action yeah <bjori> and identify all the weird mappings <MC|Sun> OK - Tony_Sun are you happy with that? <Tony_Sun> Fine by me <bjori> "sample layout" meaning the rendered html, then we can go backwards to convert it into docbook/dyndocs <MC|Sun> Right <MC|Sun> OK, well if we have no other comments, I suggest we wrap this up for the moment and work on that sample outline <bjori> sounds good <MC|Sun> Thanks everybody! <bjori> you three! <MC|Sun> In that case, time for lunch Regards, Stefan -- *********************************************************************** Sun Microsystems GmbH Stefan Hinz Sonnenallee 1 Manager Documentation, Database Group 85551 Kirchheim-Heimstetten Phone: +49-30-82702940 Germany Fax: +49-30-82702941 http://www.sun.de/mysql mailto: stefan.hinz@sun.com Amtsgericht Muenchen: HRB161028 Geschaeftsfuehrer: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer Vorsitzender des Aufsichtsrates: Martin Haering ***********************************************************************