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_ ([EMAIL PROTECTED]) 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_ ([EMAIL PROTECTED]) 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: [EMAIL PROTECTED]
Amtsgericht Muenchen: HRB161028
Geschaeftsfuehrer: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
Vorsitzender des Aufsichtsrates: Martin Haering
***********************************************************************
