Re: [PHP-DOC] Re: some remaining new doc style issues
Hi Sean, Let me start to react from the end of your mail, where you have written: | Note: I've also written a factoid bot that sits on #phpdoc that wasn't | linked above, it's tied into [PHP-DOC] and alerts us to commits, as | well. I hope I won't be shamed for that, too. This seems to suggest that you interpreted the purpose of my rant to shame you and anybody else who are developing tools for phpdoc. That was absolutely against my intention. What my aim is to: - keep the good people in the group together - get out the most of the tools we already have - build on the tools we already have Really, it's up to Dave to modify these tools for use in docweb. If he feels like it, he will, if not, he won't. The only reason they're on my server (at which phpdoc.info points) is because erigol.com was unfortunately offline for a few days/weeks and I offered to host Dave's tools. They're good tools, and we have no official place for them. What good would they do in CVS, currently? You seem to suggest two things in your mail: - the scripts on phpdoc.info were not supposed to be publicly announced - the scripts on phpdoc.info are not supposed to be open source Well, this does not seem to be a positive direction. You say that docweb is not yet ready for real use, and you are not considering looking into it because of it's state. I say, that docweb will not be ready anytime, if people do not start adding their tools and trying out / engage in conversation about tools written by others. Docweb is supposed to host tools, documentation, etc. for phpdoc and for a whole bunch of php.net documentation projects. A lot of our tools might also work for pear / php-gtk, etc. If you develop your own non-open-sourced tools, which you even try not to promote, people will start to develop their own tools, not knowing about the existing stuff. Now that we know Dave already developed a whole bunch of scripts, noone will start over from scratch, but we will wait for Dave to submit his work to the community, so others can improve on it, and that other doc projects can also benefit from the work. There is no point in starting over. The only workable way is to join forces. The most depressing sentences are the last two above. Let me repeat, what you have written: | They're good tools, and we have no official place for them. | What good would they do in CVS, currently? Looking at the scripts at http://www.phpdoc.info/erigol/, they are all tools that generate output from the CVS checkouts behind, and so they can be setup anywhere, since their output can be regenerated anywhere. There is an official place for such scripts: docweb. What good they would have there? - more people could help improve them - more documentation teams could be able to adopt them (without a need to start over from scratch) - since these scripts are supposed to sometime be placed in docweb anyway, developing with that back infrastructure (include files, layout, URL scheme etc) in mind, it would be easier later on (no need to port it to docweb) If you don't help making docweb a reality, but rather just wait for it to become cool stuff, it will never become one. Again, none of it is official. We (or at least I) don't expect it to be. The patch sites popped up out of necessity (how long were Nuno's patches available and lost in the archives before I spoke up about them? -- THERE WAS a central repository for livedocs patches: CVS, but access to it was restricted, hence the patch sites). Livedocs cvs was not a central repository for patches, but for livedocs itself. I have not seen any committed patch files (only applied ones). Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Allow me to apologize for sounding much more harsh than intended. I don't have a lot of time today, so this will be brief, but: - - I didn't intend to hide any of the tools. _my_ few tools are not ready to be committed, and I don't even know if docbot should be committed (probably not). Once they are refined, I will get around to sharing. Think of what I have on phpdoc.info as alpha. In fact, the wiki wasn't even sending mail, properly, until yesterday. - - No server is discouraging. I know there's nothing we can do about it in the immediate-term, but it's a headache for me to maintain my stuff, AND maintain the repository of it, until I see a practical use for the repository. I see your point, though, in that sharing is best, and I agree. I'd rather not commit broken/untested code to CVS until it's reached a critical mass. The problems as I see them are: 1) maintaining the repository and 2) Quick Dirty coding that works on MY server, but certainly won't work on another (dumb things like hard-coded paths) -- these take time to fix. I will get around to adapting and committing my stuff, eventually, though. | What my aim is to: | | - keep the good people in the group together | - get out the most of the tools we already have | - build on the tools we already have I agree with all of this. I was by no means trying to split the group, or hide my tools. I hope this is understood. | You seem to suggest two things in your mail: | - the scripts on phpdoc.info were not supposed to be publicly announced | - the scripts on phpdoc.info are not supposed to be open source If you append yet to each of these bullets, it becomes truth. | Well, this does not seem to be a positive direction. You say that docweb | is not yet ready for real use, and you are not considering looking into | it because of it's state. I say, that docweb will not be ready anytime, | if people do not start adding their tools and trying out / engage in | conversation about tools written by others. Docweb is supposed to host | tools, documentation, etc. for phpdoc and for a whole bunch of php.net | documentation projects. A lot of our tools might also work for pear / | php-gtk, etc. Again, I understand. It seemed a waste of time putting efforts into something that cannot be used, practically. I agree with you, though -- others could benefit from this. | If you develop your own non-open-sourced tools, which you even try not | to promote, people will start to develop their own tools, not knowing | about the existing stuff. Now that we know Dave already developed a | whole bunch of scripts, noone will start over from scratch, but we will | wait for Dave to submit his work to the community, so others can improve | on it, and that other doc projects can also benefit from the work. There | is no point in starting over. The only workable way is to join forces. Agreed. This is all temporary. (August 11, 2004, #phpdoc): 18:22 philip maybe you should work on docweb and create these little tools there 18:22 philip that way you could use sqlite or mysql, and all pear libraries 18:23 philip email goba, show him all those tools you created and how you want to put them on docweb 18:24 @erigol nah, i just don't do much php coding. 18:24 philip what do you do? 18:24 @erigol UNEMPLOYED 18:25 philip working on docweb is perfect for you then :) 18:26 philip sean too 18:26 sean ... yeah 18:26 sean when the dust settles Seems the dust is settling, and efforts will not be wasted. I'll try to ~ get some work done on docweb. (Do all phpdoc folk have karma? I forget. If not, may I please have some? (-: ) | If you don't help making docweb a reality, but rather just wait for it | to become cool stuff, it will never become one. It's very difficult for me to justify the time to maintain stuff if there's nowhere to deploy it, as I've said above. Again, I understand where you're coming from, and agree, we should all pitch in. | Livedocs cvs was not a central repository for patches, but for livedocs | itself. I have not seen any committed patch files (only applied ones). Patches would be unnecessary if we didn't have to go through the 3 people with karma. But I digress, the patch queues seem to be on the way to consolidation, and this won't be a problem in the near future. Anyway, I know you meant no harm, and neither did I. I suspect we'll be able to move forward at a much greater speed once the server is in place, we'll just need to get past the mental block of practicality in the meantime. (nice to see you on #phpdoc (-; ) (so much for brief!) S -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org iD8DBQFBNz+3WppknrQMxQIRAhcAAKCDvlVYazuLax/w0dU0RXmaZ8puQwCgnw8e EJdAqGpJP4ySgr8s20C/wqU= =beAc -END PGP SIGNATURE-
Re: [PHP-DOC] Re: some remaining new doc style issues
| You seem to suggest two things in your mail: | - the scripts on phpdoc.info were not supposed to be publicly announced | - the scripts on phpdoc.info are not supposed to be open source If you append yet to each of these bullets, it becomes truth. Good. Seems the dust is settling, and efforts will not be wasted. I'll try to ~ get some work done on docweb. (Do all phpdoc folk have karma? I forget. If not, may I please have some? (-: ) Granted. I am to ask for docweb Karma. I have not rejected a single Karma request so far :) | If you don't help making docweb a reality, but rather just wait for it | to become cool stuff, it will never become one. It's very difficult for me to justify the time to maintain stuff if there's nowhere to deploy it, as I've said above. Again, I understand where you're coming from, and agree, we should all pitch in. I see it differently. You can do a docweb checkout and start to integrate your stuff into it. Even if you don't commit your tools, you work with the codebase already. And you have a place to deploy your scripts (your own server). That means you are forward compatible, and work with the stuff already done. You can cooperate with the docweb project without an official server. Look how many guys done this with livedocs, although there is/was no official livedocs setup. | Livedocs cvs was not a central repository for patches, but for livedocs | itself. I have not seen any committed patch files (only applied ones). Patches would be unnecessary if we didn't have to go through the 3 people with karma. But I digress, the patch queues seem to be on the way to consolidation, and this won't be a problem in the near future. Those who have created patches mostly got reviews from the developers and a lot of good patches got commited. Those who tried mostly succeeded. Anyway, I know you meant no harm, and neither did I. I suspect we'll be able to move forward at a much greater speed once the server is in place, we'll just need to get past the mental block of practicality in the meantime. I suggest you don't wait for the server being place, and start to adopt the code to the site if desired (or adopt the site to your code). Since there is not much in docweb yet, it can be either way. As I have said, I don't care about the final web address or if we use subdomains or subfolders to hold project and language specific stuff, so feel free to start discussions on stuff which you are not comfortable with :) Finally those who implement will define the rules :) If the systems team does not agree on us suggesting an outside machine to stick to doc.php.net, then we can use an arbitrary (short :) web address (even phpdoc.info or some other name). The point is not the name, or how php.net-ish it will be, but to have a stable place. We only loose the MAGIC_COOKIE and some other stuff by not being under php.net, but if this is the price to pay for leaning forward quickly, then so be it. (nice to see you on #phpdoc (-; ) Not that I will be a resident there. Mostly I don't have the time. Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
(a) See Also format note role=seealso simplelist memberfunctionprint/function/member memberfunctionecho/function/member /simplelist /note That looks fine to me! (b) Parameter listing information Really good idea, but the structure is not explained clearly. Care to write an example?
Re: [PHP-DOC] Re: some remaining new doc style issues
(a) See Also format note role=seealso simplelist memberfunctionprint/function/member memberfunctionecho/function/member /simplelist /note That looks fine to me! Now all that's needed is for it to work :) (b) Parameter listing information Really good idea, but the structure is not explained clearly. Care to write an example? There are a few, the exif docs already use it. And they also live within the unofficial official phpdoc wiki: http://wiki.phpdoc.info/DocSkel/FunctionskeletonDotXml/ Regards, Philip
Re: [PHP-DOC] Re: some remaining new doc style issues
There are a few, the exif docs already use it. And they also live within the unofficial official phpdoc wiki: http://wiki.phpdoc.info/DocSkel/FunctionskeletonDotXml/ Could someone please collect all the sites already set up with docweb stuff, wikis, pepr copies, livedocs and stuff, so we don't continue with more sites getting up and going down? It would be nice to summarize the situationon [EMAIL PROTECTED] I must admit I am getting to loose the picture (who owns what domain, who is going to set up what, what is going to point where, or at least what is the intention). Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
Do you feel this should holdup the new doc style? As far as I see there are three remaining items: (a) See Also format Everyone agrees that clean markup is better than manually entering commas and and's (or entities) but how or when will this be implemented? It would be nice to have this done before moving to the new style, I can't tell if this is what you mean. Ref: http://marc.theaimsgroup.com/?l=phpdocm=109319660307520 I must admit I have not checked the simplelist output with the current stylesheets (DSSSL and XSLT), and I have not heard anybody doing so. First it needs to be tested, and then the relevant code needs to go in. If someone provides me with proper testfiles, I am willing to look into the issue in DSSSL and XSLT. Maybe I can even solve that :) (b) Parameter listing information The parameter listing lives within a variable list, and information such as reference, type, and optional all live within the methodsynopsis. The idea is to have the parser extract the information from methodsynopsis and insert said information into the variable listing. The structure (afaict) is already in place so this may not be a holdup. I don't think we need to worry about dsssl/xslt for this, only livedocs, and worry about that later. Just so we agree that the current new doc format will do. Ref: http://marc.theaimsgroup.com/?l=phpdocm=109278378703942 1. It needs to be docbook conformant. 2. It needs to be good to be used as a reference for the parameter listing. I have not seen a proposal which fits with both criteria, or I have seriosly overlooked something. (c) Constants on own page Not a big deal, everyone agreed on this. Yep. Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
There are a few, the exif docs already use it. And they also live within the unofficial official phpdoc wiki: http://wiki.phpdoc.info/DocSkel/FunctionskeletonDotXml/ Could someone please collect all the sites already set up with docweb stuff, wikis, pepr copies, livedocs and stuff, so we don't continue with more sites getting up and going down? It would be nice to summarize the situationon [EMAIL PROTECTED] I must admit I am getting to loose the picture (who owns what domain, who is going to set up what, what is going to point where, or at least what is the intention). Here's what I know: Livedocs * CVS: http://cvs.php.net/livedocs/ * Example: http://livedocs.phpdoc.info/ (Sean) * Example: http://livedocs.zirzow.dyndns.org/ (Curt) * Patches: http://livedocs.aborla.net/ (Nuno) * Patches: http://www.powertrip.co.za/livedocs/ (Jacques) Documentation tools * Tools:http://www.phpdoc.info/erigol/ * Entities: http://www.phpdoc.info/entities/ Wikis * Home: http://wiki.phpdoc.info/ * DocSkel: http://wiki.phpdoc.info/DocSkel * RFCs: http://wiki.phpdoc.info/RFC Docweb * CVS: http://cvs.php.net/docweb/ * Example: http://php.doc.keliglia.com/ (Mehdi) * Example: http://docweb.allowee.no-ip.com/ (Vincent) Regards, Philip
Re: [PHP-DOC] Re: some remaining new doc style issues
(b) Parameter listing information The parameter listing lives within a variable list, and information such as reference, type, and optional all live within the methodsynopsis. The idea is to have the parser extract the information from methodsynopsis and insert said information into the variable listing. The structure (afaict) is already in place so this may not be a holdup. I don't think we need to worry about dsssl/xslt for this, only livedocs, and worry about that later. Just so we agree that the current new doc format will do. Ref: http://marc.theaimsgroup.com/?l=phpdocm=109278378703942 1. It needs to be docbook conformant. 2. It needs to be good to be used as a reference for the parameter listing. I have not seen a proposal which fits with both criteria, or I have seriosly overlooked something. Ehem, I seriosly overlooked something. The proposal in the mail you linked above seems to be doable with all systems (if we add a role attribute to the parameter listing section/list so it is selectable via XPath and livedocs can easier intercept what needs to be renders). Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
Could someone please collect all the sites already set up with docweb stuff, wikis, pepr copies, livedocs and stuff, so we don't continue with more sites getting up and going down? It would be nice to summarize the situationon [EMAIL PROTECTED] I must admit I am getting to loose the picture (who owns what domain, who is going to set up what, what is going to point where, or at least what is the intention). Here's what I know: Livedocs * CVS: http://cvs.php.net/livedocs/ * Example: http://livedocs.phpdoc.info/ (Sean) * Example: http://livedocs.zirzow.dyndns.org/ (Curt) * Patches: http://livedocs.aborla.net/ (Nuno) * Patches: http://www.powertrip.co.za/livedocs/ (Jacques) Documentation tools * Tools:http://www.phpdoc.info/erigol/ * Entities: http://www.phpdoc.info/entities/ Wikis * Home: http://wiki.phpdoc.info/ * DocSkel: http://wiki.phpdoc.info/DocSkel * RFCs: http://wiki.phpdoc.info/RFC Docweb * CVS: http://cvs.php.net/docweb/ * Example: http://php.doc.keliglia.com/ (Mehdi) * Example: http://docweb.allowee.no-ip.com/ (Vincent) It is somewhat positive to see so many people doing things, but it is quite satiric to see that there is no common way, and everyone comes up with his own solutions. Dave, the docweb project is supposed to contain scripts used to support phpdoc workers via the web. Or if you have scripts to commit to phpdoc, then you can also commit there. Have I overlooked your tools commited to one of these modules, or there is some strong reason to start a new project? Note that if you are not going to commit your code, people will start to write the tools again and again, as it used to be... Philip/Sean, are you dissatisfied with the adoptoin of pepr to the php doc projects (as being worked on by Vincent), or you have the intention to post your RFCs on this new system later, and you are just impatient? Having RFCs, have you looked into the adopted pepr? I am really sad that the efforts tend to get disorganized by intention. Maybe when I have some idea to discuss, I will set up a new cms somewhere (probably Drupal to be inconsistent and because I love this CMS :), and post my ideas via that interface, so if someone finds it sometime, (s)he can reply to it. Would it be better? I don't think so. About the official docweb server. Noone stood up yet and shout that he set up the server we can point the doc.php.net address to. Why? Quite easy. Noone would like to step on others toes. And this is getting worse. Sometime we have been waiting for systems to set up a server for us, and it turned out that they are not open. Then some people said it will be better (and set up in days) if we do it ourselves and Mehdi/Guillaume was proposed. Seeing that this route have not worked out, Jacques set up a version of the docweb site, and adjusted the CVS code to work server independently. Now Mehdi/Guillaume keep insisting on that they will set up the server, Jacques has the server, and so we are in a dead infinite loop. Maybe if we ask three more devoted guys to set up docweb sites, they will get angry enough to start some rent and finnaly we will have one server which will work out and the others will be turned down, so those admins can also concentrate on helping the project in other ways. I feel quite silly in this situation, as I would not like to say no to Mehdi/Guillaume nor to Jacques, and I cannot decide on what way would be the best, or who will get more upset if one or the other solution is picked. While we are playing games above this issue, more and more patch sites, wikis, rfc systems, tools pop up in different locations of the web, and getting the info needed for decision making and pushing the project forward does not get easier but rather harder and harder, as finding the stuff you read yesterday get impossible. Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
(a) See Also format Everyone agrees that clean markup is better than manually entering commas and and's (or entities) but how or when will this be implemented? It would be nice to have this done before moving to the new style, I can't tell if this is what you mean. Ref: http://marc.theaimsgroup.com/?l=phpdocm=109319660307520 I must admit I have not checked the simplelist output with the current stylesheets (DSSSL and XSLT), and I have not heard anybody doing so. First it needs to be tested, and then the relevant code needs to go in. If someone provides me with proper testfiles, I am willing to look into the issue in DSSSL and XSLT. Maybe I can even solve that :) Here's something to get started with: Patch: * http://boogle.com/tmp/simplelist-patch.txt Livedocs output: * http://livedocs.phpdoc.info/index.php?l=enq=function.exif-read-data DSSSL output: * http://boogle.com/tmp/simplelist-dsssl.html XSLT output: * http://boogle.com/tmp/simplelist-xsl.html Not bad as is! ;) Regards, Philip
Re: [PHP-DOC] Re: some remaining new doc style issues
Here's something to get started with: Patch: * http://boogle.com/tmp/simplelist-patch.txt Livedocs output: * http://livedocs.phpdoc.info/index.php?l=enq=function.exif-read-data DSSSL output: * http://boogle.com/tmp/simplelist-dsssl.html XSLT output: * http://boogle.com/tmp/simplelist-xsl.html Not bad as is! ;) Well, since it is not a note semantically, I don't think we would need to have a note. Otherwise using the para variant, all the versions seem to look quite acceptable. Looking at these real list presentations, I wonder if it better useabilitywise, if we put the list items on a line, or if we list them like this. Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
(please don't take any of my paragraph replies as a whole) Gabor Hojtsy wrote: snip It is somewhat positive to see so many people doing things, but it is quite satiric to see that there is no common way, and everyone comes up with his own solutions. I can't speak for the others, but I think I've clearly labeled my contributions unofficial, and do not think of them as anything more. There are a few of us (including Dave, and Philip, as you address, below) that use some/all of these tools regularly, and we regularly help each other out through #phpdoc on freenode. Dave, the docweb project is supposed to contain scripts used to support phpdoc workers via the web. Or if you have scripts to commit to phpdoc, then you can also commit there. Have I overlooked your tools commited to one of these modules, or there is some strong reason to start a new project? Note that if you are not going to commit your code, people will start to write the tools again and again, as it used to be... Really, it's up to Dave to modify these tools for use in docweb. If he feels like it, he will, if not, he won't. The only reason they're on my server (at which phpdoc.info points) is because erigol.com was unfortunately offline for a few days/weeks and I offered to host Dave's tools. They're good tools, and we have no official place for them. What good would they do in CVS, currently? Philip/Sean, are you dissatisfied with the adoptoin of pepr to the php doc projects (as being worked on by Vincent), or you have the intention to post your RFCs on this new system later, and you are just impatient? Having RFCs, have you looked into the adopted pepr? Again, I can't speak for Philip, but yes, I am impatient. My Nomenclature RFC is nothing more than a work in progress. The wiki serves it well, and when I feel it is ready, I will either post it to PEPr (if that's ready by then), or post it to the list. Again, this is all unofficial. As for Philip's DocSkel RFC, I took the liberty of adopting the skeleton he was hosting in a .zip file on boogle.com and posting it on the wiki, because I wanted to make a few changes, and it's extremely difficult to patch a .zip. The wiki lends well to this situation, and when asking around, the general concensus (from Derick, especially, IIRC) is that systems@ is not interested in hosting/managing a wiki. So I am. PEPr does not exist for doc purposes, yet. In the interim, peoples' ideas should not stop flowing. Docweb is new. There's no way to USE PEPr, yet, officially. Do you propose we set up individual PEPrs and use them? of course not. That is no different than the collection of links, above. I am really sad that the efforts tend to get disorganized by intention. Maybe when I have some idea to discuss, I will set up a new cms somewhere (probably Drupal to be inconsistent and because I love this CMS :), and post my ideas via that interface, so if someone finds it sometime, (s)he can reply to it. Would it be better? I don't think so. Your sarcasm is appreciated, but I was (and am still) not officially soliciting replies to my Nomenclature RFC. If I was, it would've been posted to the list. If someone stumbles upon it, and has some input, great, but I'm not looking for much, right now, other than asking the guys on #phpdoc what they think. I'm also not hurt that nobody has searched me out and found my RFC and made modifications to it, or patted me on the back. I was even surprised to see the wiki posted to [PHP-DOC] this morning. About the official docweb server. snipno reply, just get it done! (-; /snip While we are playing games above this issue, more and more patch sites, wikis, rfc systems, tools pop up in different locations of the web, and getting the info needed for decision making and pushing the project forward does not get easier but rather harder and harder, as finding the stuff you read yesterday get impossible. Again, none of it is official. We (or at least I) don't expect it to be. The patch sites popped up out of necessity (how long were Nuno's patches available and lost in the archives before I spoke up about them? -- THERE WAS a central repository for livedocs patches: CVS, but access to it was restricted, hence the patch sites). The fact remains: doc-web does not yet exist. Once we get something official (like maybe a domain name with attached server, and a functioning checkout of the module?), people like myself might be inclined to commit some code. In the mean-time, I'd rather USE (and allow others to use) the tools I've written instead of watching them rot in a CVS repository that may or may not see the light of day, depending on who has bigger toes. As I see it, there are two central points of gathering for the php-doc team: the mailing list(s) and CVS. If you read stuff yesterday and it wasn't in one of those two places, it shouldn't be considered official, and should not impede your work. Note: I've also written a
Re: [PHP-DOC] Re: some remaining new doc style issues
As far as the phpdoc.info stuff goes, this all came about through the active #phpdoc channel on freenode. Many of us work together on various tasks so various people created tools. I see it as a testing ground for docweb but the docweb situation is unknown right now so until it's figured out we keep on working offsite. Again, to be clear, IMHO all the stuff listed is meant to go in docweb one day. It's much easier and comfortable to get a prototype going at home then start from scratch on some public server, especially when that server barely even exists. Is docweb ready for all of this? If so, it would be nice if Sean, Dave, and Curt joined that project. The wiki is nice, it's a place for us to collaborate on ideas and work on proposals until said proposals are actually proposed. This is especially true for the DocSkel. Pepr is not ready and we just needed a place to write stuff. So yes, we're impatient. It also works well for us to remember URLS and information, and has also been used to test how well a wiki would work for various tasks. Like the HOWTO. As far as livedocs goes, I assume a patch system will exist on docweb. As far as the server situation, I am way out of the loop on that but AFAICT one group started and for various reasons failed so it's time to move on to the next. In other words, use Jacques server. This is the same for a PHP mirror, once it's moved to another server that's it. Regards, Philip
Re: [PHP-DOC] Re: some remaining new doc style issues
Not bad as is! ;) Well, since it is not a note semantically, I don't think we would need to have a note. Otherwise using the para variant, all the versions seem to look quite acceptable. Looking at these real list presentations, I wonder if it better useabilitywise, if we put the list items on a line, or if we list them like this. I prefer the list style (separate lines), and with the bullets. Regards, Philip
Re: [PHP-DOC] Re: some remaining new doc style issues
Not bad as is! ;) Well, since it is not a note semantically, I don't think we would need to have a note. Otherwise using the para variant, all the versions seem to look quite acceptable. Looking at these real list presentations, I wonder if it better useabilitywise, if we put the list items on a line, or if we list them like this. I prefer the list style (separate lines), and with the bullets. OK, so then only the DSSL and XSLT sheets need changing to use list markup instead of silly table markup for the simple lists. BTW it is very silly to use tables for lists, huh... Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
Not bad as is! ;) Well, since it is not a note semantically, I don't think we would need to have a note. Otherwise using the para variant, all the versions seem to look quite acceptable. Looking at these real list presentations, I wonder if it better useabilitywise, if we put the list items on a line, or if we list them like this. I prefer the list style (separate lines), and with the bullets. OK, so then only the DSSL and XSLT sheets need changing to use list markup instead of silly table markup for the simple lists. BTW it is very silly to use tables for lists, huh... Well, that table is not that much odd, if you check the simplelist docs. It documents three types of rendering or which the vertical is the default (which is still multicolumned). None of the versions match our current expectation (or does inline match it, so there is no ending dot?) http://docbook.org/tdg/en/html/simplelist.html BTW I have just checked the XSL sheets, and they do this quite fine. It is very easy to make this simplelist look like a list, but then we need to check if we use simplelists for something else, so we will not break rendering elsewhere (or we need to mark our simplelist with some role again). Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
As far as the server situation, I am way out of the loop on that but AFAICT one group started and for various reasons failed so it's time to move on to the next. In other words, use Jacques server. This is the same for a PHP mirror, once it's moved to another server that's it. +1 .. I'm really sorry for all this wasted time. The problem is that the situation was totaly out of my reach after I left nexen because of a huge conflict. I didn't want to give up waiting to offer (it was a gift from nexen and poz company btw) this server to the doc project. I should have speaked before, but the decision involved some personal decisions too (it's all in my head). In the same time, I've been 12/7 busy writing a project for my new employer. Didn't have the time to realize the big need for the decision as well as I didn't have the time to follow and answer the threads about PECL, livedocs, see also, etc.. You may have noticed that lately I've been taking care of smarty, xslt, dom, bc, imap. That's the tools I used for the project, and I only had the time to commit some fixes and additions to the documentation I was reading all day. I'd like to thank Guillaume for all the time he managed to find to help with the situation, I know the lot of real daily work he have. I'll get back Vincent (poz) disks and will send them to him or Jacques if he need them for the server. The server will be hosting a lot of huge checkouts and performing a lot of filesystem calls once the site is running officially and Vincent disks are sweeted for this usage. Jacques ? :) The other decision we should take ASAP is to merge our efforts in CVS, even if we have to host them unoficially (means without the php.net and with all our faith) forever :) Dave's scripts can be hacked to fit to pear, gtk, smarty docs too (entities, sources vs documented stuff, missing examples in function references). This is exactly what the sources in the docweb repository are designed for. Why not also having a general wiki and one per sub-project ? The editing privilege is only granted to php.net members and I'm sure we can manage to have automatic commits to doc-web@ when someone edit something. This can totally replace a need for CVS updated texts on the site. The main entry point is the wiki hacked to have the menu bar too and that's it ! Jacques and Nuno should join their effort to make _one_ generic (per project) patch system that will be hosting the discussed patches for livedocs, as well as the other projects. What else did I miss ? Pepr. Pepr is sweet, but I'm not sure we should depend on it. He seemed buggy on Allowe site (I'll send reports later), we are obliged to maintain the updates from pearweb by hand, he needs PEAR, and Philip's RFC looks quiet good in the wiki. If we hack the wiki to have emails sent to the doc, it will sweet what we need: a voting system. I'd like to hear from all of you guys on this merge proposal. I'm sure I have missed a lot of points. Gabor, thank you a *lot* for your patience and help getting the thing moving. Keep up, we'll have it online ;) I'll be releasing my work project next week and will have a normal phpdoc guy life again soon ;) didou
Re: [PHP-DOC] Re: some remaining new doc style issues
Hi, This has been discussed many times with many dead ends. Here are some see also threads: http://marc.theaimsgroup.com/?l=phpdocm=100894842011360 http://marc.theaimsgroup.com/?l=phpdocm=101051061316162 http://marc.theaimsgroup.com/?l=phpdocm=105601918607181 One structure that was proposed is as follows. Not sure why it wasn't implemented, let's wait until Goba comes back from vacation to answer this :) note role=seealso simplelist memberfunctionprint/function/member memberfunctionecho/function/member /simplelist /note I can't find any mention of listendand; on the lists, and from RFC/2003_meeting_findings.txt is this: About see also lists, the attendees of the meeting concluded in that the current see also writing scheme is fine, and there is no need to modify it. In summary: Not sure what happened with this idea. It seemed like everyone wanted the structured see also (no commas, no and...) as to let XSL/Livedocs deal with the style but it never happened. Let's see what Goba says on this. I have implemented listendand; in the author list, because I needed a quick way to add a list which will work among translations too automatically. I had no intention to start tweaking the sheets, or wait for some solution, since it was already too late to start crediting contributors. Now that we can give more thought to it, it is clearly visible that a markup-rich solution is better, which shows us the structure of the list. For see also lists, the role would enable DSSSL and XSLT sheets to find out how the list items need to be separated and how the last item needs to be printed. It might also happen that simplelist already works this way (I have not tried it). Why I have not shouted in to oppose the continued use of listeandand; is that the use of this entity makes these kind of lists instantly findable in the source, so we can convert to a semantically better markup later if need be. However since there are already so much to do around the files, the changing of the see also lists might not be that big of a task anyway. Ps. Thanks for Mehdi to get this to my attention again. This was on my (very long) TODO list somewhere :) Goba
Re: [PHP-DOC] Re: some remaining new doc style issues
Now that we can give more thought to it, it is clearly visible that a markup-rich solution is better, which shows us the structure of the list. For see also lists, the role would enable DSSSL and XSLT sheets to find out how the list items need to be separated and how the last item needs to be printed. It might also happen that simplelist already works this way (I have not tried it). Why I have not shouted in to oppose the continued use of listeandand; is that the use of this entity makes these kind of lists instantly findable in the source, so we can convert to a semantically better markup later if need be. However since there are already so much to do around the files, the changing of the see also lists might not be that big of a task anyway. Do you feel this should holdup the new doc style? As far as I see there are three remaining items: (a) See Also format Everyone agrees that clean markup is better than manually entering commas and and's (or entities) but how or when will this be implemented? It would be nice to have this done before moving to the new style, I can't tell if this is what you mean. Ref: http://marc.theaimsgroup.com/?l=phpdocm=109319660307520 (b) Parameter listing information The parameter listing lives within a variable list, and information such as reference, type, and optional all live within the methodsynopsis. The idea is to have the parser extract the information from methodsynopsis and insert said information into the variable listing. The structure (afaict) is already in place so this may not be a holdup. I don't think we need to worry about dsssl/xslt for this, only livedocs, and worry about that later. Just so we agree that the current new doc format will do. Ref: http://marc.theaimsgroup.com/?l=phpdocm=109278378703942 (c) Constants on own page Not a big deal, everyone agreed on this. We could get away with what we have now and it'll all work fine in both livedocs and dsssl but...I guess it comes down to who's our dsssl guru, and where do they live :) Regards, Philip
Re: [PHP-DOC] Re: some remaining new doc style issues
I agree with everything except the seealso. Let's formalise it and let XSL do the hard work. We can make a simplelist, or find some relevant docbook tag, sticking the entity in is a bit dirty.
