Re: [PHP-DOC] RFC: Re-organizing function reference part
> > Commenting the categories list, I don't think > > that categories, with only one item should be > > opened (eg. Search or URL or Data Exchange). > > Yes, under Miscellaneous, unless some other module > too gets moved under those categories. I see that you have opened them to start discussion about putting more items inside (eg. Data exchange). :) Goba
Re: [PHP-DOC] RFC: Re-organizing function reference part
> On Sun, 2 Sep 2001, Jeroen van Wolffelaar wrote: > > > I would merge "string/character" and "Variables,types and function > > handling", and name it: > > "basic functions", since they are very general-purpose, do NOT have external > > depencies (like mysql, etc), and are quite close to the language. > > Error-handling, program execution are also good candidates for "basic > > functions", along with probably others? > > That's quite a relevant way too to categorize sections. My problem is that > I actually haven't any kind of opinion, I could argue for both > alternatives... There are simply multiple ways of doing this, and there's no real rule to do the one or the other... I think that at least all functions which are basic (i.e. no extension like pspell, a database, xml, or something, but simply work with strings and numbers without being very specific) should be in the first (or the first few, if they can be split up) sections. I don't think that that category will be too large then... Databases is bigger, but that's really because of a design-lack in PHP: it should have been all different functions... > I might go to a local bookstore next week and check some PHP books from > different publishers. If there's some common categories under which some > function groups seem to always fall, it could be because publishers may > have done some research on how to present information the most clear way. Good idea, I must admid I have no single book about PHP, nor ever read one... --jeroen > > -- Jouni > >
Re: [PHP-DOC] RFC: Re-organizing function reference part
On Sun, 2 Sep 2001, Jeroen van Wolffelaar wrote: > I would merge "string/character" and "Variables,types and function > handling", and name it: > "basic functions", since they are very general-purpose, do NOT have external > depencies (like mysql, etc), and are quite close to the language. > Error-handling, program execution are also good candidates for "basic > functions", along with probably others? That's quite a relevant way too to categorize sections. My problem is that I actually haven't any kind of opinion, I could argue for both alternatives... I might go to a local bookstore next week and check some PHP books from different publishers. If there's some common categories under which some function groups seem to always fall, it could be because publishers may have done some research on how to present information the most clear way. -- Jouni
Re: [PHP-DOC] RFC: Re-organizing function reference part
I would merge "string/character" and "Variables,types and function handling", and name it: "basic functions", since they are very general-purpose, do NOT have external depencies (like mysql, etc), and are quite close to the language. Error-handling, program execution are also good candidates for "basic functions", along with probably others? --jeroen
Re: [PHP-DOC] RFC: Re-organizing function reference part
On Sun, 2 Sep 2001, Hojtsy Gabor wrote: > What do you think about these additional groups? > > Variables, types and function handling > Array > Class-object > Function handling > Variable > Session handling > > Miscellaneous: > Apache-specific > Error handling and logging > GNU readline > PHP options & information > Program execution > Printer > Semaphore and shared memory > Shared memory Fine. I was just too lazy to invent them myself :) > Commenting the categories list, I don't think > that categories, with only one item should be > opened (eg. Search or URL or Data Exchange). Yes, under Miscellaneous, unless some other module too gets moved under those categories. -- Jouni
Re: [PHP-DOC] RFC: Re-organizing function reference part
What do you think about these additional groups? Variables, types and function handling Array Class-object Function handling Variable Session handling Miscellaneous: Apache-specific Error handling and logging GNU readline PHP options & information Program execution Printer Semaphore and shared memory Shared memory Commenting the categories list, I don't think that categories, with only one item should be opened (eg. Search or URL or Data Exchange). Goba
Re: [PHP-DOC] RFC: Re-organizing function reference part
On Sun, 26 Aug 2001, Egon Schmid wrote: > It would be nice, if someone could make a first draft about the > names of new chapters and which sections could be within sections. Ok, here it is. And it's really a very rough draft... based on bug types in bug reporting system, but not exactly the same. -- Jouni Compression functions Bzip2 ZIP file Zlib compression Date/Time/Calendar Calendar Date and time ICAP MCAL Directory/Filesystem Directory Filesystem Directory Services LDAP YP/NIS Database Database (dbm-style) abstraction DBM dbx DB++ FrontBase filePro Hyperwave -- under this category in bug reporting, doesn't fit well here IMHO Informix InterBase Ingres II Microsoft SQL server mSQL MySQL Unified ODBC Oracle 8 Oracle Ovrimos PostgreSQL Sesam database Sybase Data exchange WDDX Encryption and hash Mcrypt Mhash OpenSSL -- could be in Network as well Extensibility COM Java Satellite CORBA -- will be deprecated Universe -- not yet written? E-commerce CCVS CyberCash CyberMUT Verisign Payflow Pro Graphics Image Ming Shockwave Flash Languages/Translation Gettext GNU recode iconv Multibyte-string Mail IMAP, POP3 and NNTP Mail functions Math BCMath GMP Mathematical functions Network CURL -- fits better here than under URL FTP HTTP IRC Gateway Network SNMP Socket YAZ -- or under data exchange, as in bug types? PDF ClibPDF Forms Data Format -- would fit under data exchange as well PDF Regular expressions Perl-compatible POSIX extended Spelling Aspell Pspell Search mnoGoSearch String/character Character type String XML DOM XML XML Parser XSLT URL URL Things that didn't fit well under any category (at least for me...) Apache-specific Array Class-object Error handling and logging Function handling GNU readline PHP options & information Program execution Printer Semaphore and shared memory Shared memory -- we seem to have to different versions Session handling Variable
Re: [PHP-DOC] RFC: Re-organizing function reference part
> > > - New subtitles must be agreed on and added to each language-defs.ent. > > > > This is what needs to be the same for the bug system. So if it is > > not right, we should collect the functions and make a new category > > system, and start to use it in the bug system and here too. > > Something very near to it, but not actually the same. I think we can > safely leave out for example 'Website problems' and 'Reproducible crash' > from the manual :) Erm, yes, you are right :)) > At least the left part listing links to different parts Function reference > in the online manual should be re-organized the same way. The PHP code is generated with DSSSL style sheets. The menus are printed from arrays, and the arrays are in the generated code. So maybe some small changes need to be made in the PHPweb code, but the main thing is the DSSSL style sheets. > Yes, let's wait for Hartmut to come back from hiking and drinking beer. If > we do these things at the same time, it should be possible to declare > maybe a 24-36 hours time when commits are not posted to the list. The > patches would be really mega-sized and this seems be a great inconvenience > to some of the people on this list. +1 Goba
Re: [PHP-DOC] RFC: Re-organizing function reference part
On Sun, 26 Aug 2001, Hojtsy Gabor wrote: > > - New subtitles must be agreed on and added to each language-defs.ent. > > This is what needs to be the same for the bug system. So if it is > not right, we should collect the functions and make a new category > system, and start to use it in the bug system and here too. Something very near to it, but not actually the same. I think we can safely leave out for example 'Website problems' and 'Reproducible crash' from the manual :) > > - I guess that some scripts relating to the online HTML-manual should > > be fixed. Not sure though. > > As long as we can get the file names stay the same, there is > nothing [I can think of] to modify in the scripts at phpweb. > The notes are binded by file names, so this is why the file > names are important for us. At least the left part listing links to different parts Function reference in the online manual should be re-organized the same way. > Erm, if we start to change things in a way like that, we can > also start paralelly on proofing the "split up the function > reference by functions into files" plan. This was a great plan > IMHO, and [if we can agree in both cases] we should make the > two changes the same time, instead of two separate > repository-wide changes. Yes, let's wait for Hartmut to come back from hiking and drinking beer. If we do these things at the same time, it should be possible to declare maybe a 24-36 hours time when commits are not posted to the list. The patches would be really mega-sized and this seems be a great inconvenience to some of the people on this list. -- Jouni
Re: [PHP-DOC] RFC: Re-organizing function reference part
On Sun, 26 Aug 2001, Egon Schmid wrote: > It would be nice, if someone could make a first draft about the > names of new chapters and which sections could be within sections. Something very near to the list of bug types bugs.php.net. I think there actually was a draft some time ago, but I'll have to go through the mail-archives. > I could only guess, but I think, Hartmut is at The > Linuxbierwanderung (Linux Beer Hike) and this hike ends on > 09/01/2001. He'll have time to part in this discussion later. As the change is quite big and needs cooperation from so many people, I think we should proceed quite slowly and think everything really through. I'm thinking something like the last weekend of September for a possible date for this change. -- Jouni
Re: [PHP-DOC] RFC: Re-organizing function reference part
> Can be done without any hurry before the change: > - Modify the *.dsl files so that TOC is created the right way. Some small > fixing with HTML version, a bit more with printable versions. I will > volunteer, unless Hartmut explicitly requests to have the honour... > - New subtitles must be agreed on and added to each language-defs.ent. This is what needs to be the same for the bug system. So if it is not right, we should collect the functions and make a new category system, and start to use it in the bug system and here too. > - I guess that some scripts relating to the online HTML-manual should > be fixed. Not sure though. As long as we can get the file names stay the same, there is nothing [I can think of] to modify in the scripts at phpweb. The notes are binded by file names, so this is why the file names are important for us. > - Probably more... Erm, if we start to change things in a way like that, we can also start paralelly on proofing the "split up the function reference by functions into files" plan. This was a great plan IMHO, and [if we can agree in both cases] we should make the two changes the same time, instead of two separate repository-wide changes. > Can be done only after the re-organization, and with great hurry, because > the change will temporarily break a lot of things: > - Change the tags, and within , add tags around s > and s and change s to s, because the DTD > requires this. Maybe somebody can write scripts for these tasks, and test if they are working well (a good place for these scripts is the scripts dir under phpweb :). [See the readme there]. > Comments? I think the ideas are OK, and we can go on discuss this. I am against nothing with this plan this time. Goba
Re: [PHP-DOC] RFC: Re-organizing function reference part
> This topic has popped up a few times before on the list, and I think I've > seen even bug report(s?) claiming that the current function reference > part makes it hard to find information, because it has grown so big. But I > don't remember that we would haver ever deciced either to do it or not do > it... I have discussed this with Hartmut a bit and your solution seems working. > The main problem is that in DocBook, we can't splice an additional level > between a and . What I could come up with by reading > DocBook reference is the following: > > -- Function reference > -- General category of functions, >ie. like "Database functions" >-- replaces reference, not allowed here, >ie. like "MySQL functions" > -- replaces partintro, not allowed here > -- the original refentry text It would be nice, if someone could make a first draft about the names of new chapters and which sections could be within sections. > Can be done without any hurry before the change: > - Modify the *.dsl files so that TOC is created the right way. Some small > fixing with HTML version, a bit more with printable versions. I will > volunteer, unless Hartmut explicitly requests to have the honour... I could only guess, but I think, Hartmut is at The Linuxbierwanderung (Linux Beer Hike) and this hike ends on 09/01/2001. > - New subtitles must be agreed on and added to each language-defs.ent. > - I guess that some scripts relating to the online HTML-manual should > be fixed. Not sure though. > - Probably more... > > Can be done only after the re-organization, and with great hurry, because > the change will temporarily break a lot of things: > - Change the tags, and within , add tags around s > and s and change s to s, because the DTD > requires this. > - Probably more... > > So, if this will ever happen, the change should be planned carefully and > slowly, make sure that we've got everything ready, and all the translators > should be aware of what's going on and can make a few hours available to > fix broken things within a day or two after the change. Which should > happen on a day commonly agreed upon, preferable at least a week before. > > Comments? I am for a change. -Egon
[PHP-DOC] RFC: Re-organizing function reference part
This topic has popped up a few times before on the list, and I think I've seen even bug report(s?) claiming that the current function reference part makes it hard to find information, because it has grown so big. But I don't remember that we would haver ever deciced either to do it or not do it... The main problem is that in DocBook, we can't splice an additional level between a and . What I could come up with by reading DocBook reference is the following: -- Function reference -- General category of functions, ie. like "Database functions" -- replaces reference, not allowed here, ie. like "MySQL functions" -- replaces partintro, not allowed here -- the original refentry text I did some testing, and this seems to work quite well, although there are of course some problems to solve first. Things that must be modified, *if* we come to an agreement that we reorganize the function reference: Can be done without any hurry before the change: - Modify the *.dsl files so that TOC is created the right way. Some small fixing with HTML version, a bit more with printable versions. I will volunteer, unless Hartmut explicitly requests to have the honour... - New subtitles must be agreed on and added to each language-defs.ent. - I guess that some scripts relating to the online HTML-manual should be fixed. Not sure though. - Probably more... Can be done only after the re-organization, and with great hurry, because the change will temporarily break a lot of things: - Change the tags, and within , add tags around s and s and change s to s, because the DTD requires this. - Probably more... So, if this will ever happen, the change should be planned carefully and slowly, make sure that we've got everything ready, and all the translators should be aware of what's going on and can make a few hours available to fix broken things within a day or two after the change. Which should happen on a day commonly agreed upon, preferable at least a week before. Comments? -- Jouni
