Re: [PHP-DOC] [RFC] Updates to translations
On Fri, Dec 5, 2008 at 07:28, Kalle Sommer Nielsen <[EMAIL PROTECTED]> wrote: > 2008/12/4 Hannes Magnusson <[EMAIL PROTECTED]>: >> Using a revision attribute (like proposed last year, and again >> recently) on the root elements of all chunks would however possibly >> make it possible. >> PhD could read the revision attribute of all chunks and register the >> revision to the xml:id, then when building translations it could >> compare those revisions and mark the xml:id/chunk as outdated (i.e. >> pregenerate "this page is outdated" into the header or something). > > How much would be needed for this? I know that revcheck probably will > break aswell as all translations. But from your point of view would it > be reasonable to make that change? We would have to update all the translations and remember to bump their EN-Revisions too (which actually will no longer exist, the "EN-Revision" would be the revision="" attribute) if the file is up2date. We would also have to update various translation scripts I guess. I'm not entirely sure how much work it will be all together, maybe a days work (updating the XML and PhD)... -Hannes
Re: [PHP-DOC] [RFC] Updates to translations
2008/12/4 Hannes Magnusson <[EMAIL PROTECTED]>: > On Thu, Dec 4, 2008 at 07:20, Kalle Sommer Nielsen <[EMAIL PROTECTED]> wrote: >> 1) Translation bugs >> Theres many translation bugs reported [1] reported to the bug tracker >> and I don't think that many translators check for bugs in there. So I >> propose we add a link to the docweb site for when you're focusing on a >> specific translation to eg. say: >> >> Project (documentation) bugs >> 53 open bugs >> 4 open translation bugs > > Sounds good. > > When I browse these bugs I tend to prefix the titles with [LANG] to > make it easier for translators to identify bugs in their languages. > > >> Aswell as sending a perhaps monthly email to their mailing list, like >> the bug summary being sent to internals. > > To all ~30 lists? I don't think thats gonna help. > > >> 2) Many of the reported translation bugs as said above are related to >> outdated versions of a file, I think we should put a notice on the >> manual pages if a page is outdated so people don't miss information or >> features that may be useful to them aswel as a link to the english >> version of the page. > > There is already a feature request for that behaviour, but due to our > entity include magic PhD has no chance of figuring out which page is > what, and therefore no chance of comparing file revisions. > > Using a revision attribute (like proposed last year, and again > recently) on the root elements of all chunks would however possibly > make it possible. > PhD could read the revision attribute of all chunks and register the > revision to the xml:id, then when building translations it could > compare those revisions and mark the xml:id/chunk as outdated (i.e. > pregenerate "this page is outdated" into the header or something). How much would be needed for this? I know that revcheck probably will break aswell as all translations. But from your point of view would it be reasonable to make that change? > > -Hannes > -- Kalle Sommer Nielsen
Re: [PHP-DOC] [RFC] Updates to translations
2008/12/4 Philip Olson <[EMAIL PROTECTED]>: >> 1) Translation bugs >> Theres many translation bugs reported [1] reported to the bug tracker >> and I don't think that many translators check for bugs in there. So I >> propose we add a link to the docweb site for when you're focusing on a >> specific translation to eg. say: >> >> Project (documentation) bugs >> 53 open bugs >> 4 open translation bugs >> >> Aswell as sending a perhaps monthly email to their mailing list, like >> the bug summary being sent to internals. > > Unfortunately our bug system is not equipped for this task so the coding and > maintaining of this currently wouldn't be the most fun... but it's a fine > idea and certainly doable. > > A few options that come to mind: > - Add new feature to bugs web, which would involve changes to the db schema > - Parse the subjects on the docweb server (via RSS downloaded from bugs web) > - Add slow queries on bugs web that parses the subject (not a good idea) > - Add new "Type of Bug" for each language (not a good idea) > - ... If the bug system was modified to return a serialized string of the search results aswell as allowing wildcards for bug title it could work pretty smooth. Then we could filter out bugs that matches: [$iso_lang_code] * > > Note: We've been pretty good about maintaining [LANG] in subjects for the > translation bugs. > >> 2) Many of the reported translation bugs as said above are related to >> outdated versions of a file, I think we should put a notice on the >> manual pages if a page is outdated so people don't miss information or >> features that may be useful to them aswel as a link to the english >> version of the page. > > This is a good idea and on the table, specifically the following bug report: > > http://bugs.php.net/44903 I like Hannes' suggestion on this. > > Regards, > Philip > -- Kalle Sommer Nielsen
Re: [PHP-DOC] [RFC] Updates to translations
On Thu, Dec 4, 2008 at 07:20, Kalle Sommer Nielsen <[EMAIL PROTECTED]> wrote: > 1) Translation bugs > Theres many translation bugs reported [1] reported to the bug tracker > and I don't think that many translators check for bugs in there. So I > propose we add a link to the docweb site for when you're focusing on a > specific translation to eg. say: > > Project (documentation) bugs > 53 open bugs > 4 open translation bugs Sounds good. When I browse these bugs I tend to prefix the titles with [LANG] to make it easier for translators to identify bugs in their languages. > Aswell as sending a perhaps monthly email to their mailing list, like > the bug summary being sent to internals. To all ~30 lists? I don't think thats gonna help. > 2) Many of the reported translation bugs as said above are related to > outdated versions of a file, I think we should put a notice on the > manual pages if a page is outdated so people don't miss information or > features that may be useful to them aswel as a link to the english > version of the page. There is already a feature request for that behaviour, but due to our entity include magic PhD has no chance of figuring out which page is what, and therefore no chance of comparing file revisions. Using a revision attribute (like proposed last year, and again recently) on the root elements of all chunks would however possibly make it possible. PhD could read the revision attribute of all chunks and register the revision to the xml:id, then when building translations it could compare those revisions and mark the xml:id/chunk as outdated (i.e. pregenerate "this page is outdated" into the header or something). -Hannes
Re: [PHP-DOC] [RFC] Updates to translations
1) Translation bugs Theres many translation bugs reported [1] reported to the bug tracker and I don't think that many translators check for bugs in there. So I propose we add a link to the docweb site for when you're focusing on a specific translation to eg. say: Project (documentation) bugs 53 open bugs 4 open translation bugs Aswell as sending a perhaps monthly email to their mailing list, like the bug summary being sent to internals. Unfortunately our bug system is not equipped for this task so the coding and maintaining of this currently wouldn't be the most fun... but it's a fine idea and certainly doable. A few options that come to mind: - Add new feature to bugs web, which would involve changes to the db schema - Parse the subjects on the docweb server (via RSS downloaded from bugs web) - Add slow queries on bugs web that parses the subject (not a good idea) - Add new "Type of Bug" for each language (not a good idea) - ... Note: We've been pretty good about maintaining [LANG] in subjects for the translation bugs. 2) Many of the reported translation bugs as said above are related to outdated versions of a file, I think we should put a notice on the manual pages if a page is outdated so people don't miss information or features that may be useful to them aswel as a link to the english version of the page. This is a good idea and on the table, specifically the following bug report: http://bugs.php.net/44903 Regards, Philip
[PHP-DOC] [RFC] Updates to translations
Right So I had this idea for sometime now, its actually two ideas for translations of the manual, which is as follows: 1) Translation bugs Theres many translation bugs reported [1] reported to the bug tracker and I don't think that many translators check for bugs in there. So I propose we add a link to the docweb site for when you're focusing on a specific translation to eg. say: Project (documentation) bugs 53 open bugs 4 open translation bugs Aswell as sending a perhaps monthly email to their mailing list, like the bug summary being sent to internals. 2) Many of the reported translation bugs as said above are related to outdated versions of a file, I think we should put a notice on the manual pages if a page is outdated so people don't miss information or features that may be useful to them aswel as a link to the english version of the page. What are your thoughts on these? -- Kalle Sommer Nielsen
Re: [PHP-DOC] RFC: acronyms.xml
Hi, Choices: a) /phpdoc/ b) /phpdoc/entities/ c) /phpdoc/somenewdir/ d) ... Although it's not really a list of entities the file can go in that folder. It would be the simplest. Note: this file is not language specific so only one copy will exist. Entities might be a good choice. agreeded, as they don't need to be translated. Why acronyms.xml? It replaces our use of (in XML) with the appropriate in generated HTML. Please comment with what you think. A concern is whether we need to worry about having multiple meanings for one acronym but it seems we can ignore that for now as the manual will most likely use only one meaning. And btw, the above has now been implemented in Livedocs :-) IMHO go ahead. Goba Same here ;) (and I know this was a long standing item in your TODO list :) ) Nuno
Re: [PHP-DOC] RFC: acronyms.xml
Hi, Choices: a) /phpdoc/ b) /phpdoc/entities/ c) /phpdoc/somenewdir/ d) ... Although it's not really a list of entities the file can go in that folder. It would be the simplest. Note: this file is not language specific so only one copy will exist. Entities might be a good choice. Why acronyms.xml? It replaces our use of (in XML) with the appropriate in generated HTML. Please comment with what you think. A concern is whether we need to worry about having multiple meanings for one acronym but it seems we can ignore that for now as the manual will most likely use only one meaning. And btw, the above has now been implemented in Livedocs :-) IMHO go ahead. Goba
[PHP-DOC] RFC: acronyms.xml
Hello everyone! This RFC is for a new acronyms.xml and has two main points: 1. File location in phpdoc: Choices: a) /phpdoc/ b) /phpdoc/entities/ c) /phpdoc/somenewdir/ d) ... Although it's not really a list of entities the file can go in that folder. It would be the simplest. Note: this file is not language specific so only one copy will exist. 2. The DocBook markup: I chose a variablelist as it's pretty straightforward. Another option is to use glossentry but it adds complexities that we don't really need. Example: Acronyms List ASCII American Standard Code for Information Interchangesimpara> RFC Request For Comments Why acronyms.xml? It replaces our use of (in XML) with the appropriate in generated HTML. Please comment with what you think. A concern is whether we need to worry about having multiple meanings for one acronym but it seems we can ignore that for now as the manual will most likely use only one meaning. And btw, the above has now been implemented in Livedocs :-) Regards, Philip
Re: [PHP-DOC] RFC/xml_validation
Hi, I've tried to make validation check on my WIN system without cygwin, jade and nsgmls and found some strange things about PHPDOC build system. I'll be glad if somebody could read this and answer my questions. =) Well, I am trying to decipher what you try to tell us, but sometimes it is quite hard... xmllint needs to be run several times. (A) The first run should be used to detect wrong entities, without trailing ; This errors should be fixed on the fly with a php script. (B) The second run should be used to detect valid missing entities. (c) The third run should be used to detect valid missing ids. Multiple runs of xmllint seems to be necessary. As long as wrong entities (without trailing ;) exists, the error output is not usable to create valid missing entities. Also is seems there is no way to convince convince xmllint to report errors for missing entities and missing IDREFS in the same run. 1. Is the problem with missing ; still in place? Xmllint does the job pretty well, but is it really necessary to include additional PHP layer for processing xmllint messages? Every editor's highlightning engine can point out missing ; in xml entity, so I doubt there are many such errors. Not everybody is using highlighting editors. Also saying that everyone will do just fine is not a good point. We have seen recently that some very experienced doc people committed code, which made 'make test' shout. The thing that it is possible does not mean it will work out. The missing entity and id handling is in place to let the manual build / display with livedocs even if there are some small errors. This is not to stop the automatic manual generation from updates, especially in these times manual updates are only done monthly or so... Even if we switch to using "make test_xml" in place of "make test", there is a chance, that people will not run it. So regardless of the fact that it would find the ;-less entities perfectly, it does not help in itself. (B) The second run should be used to detect valid missing entities. (c) The third run should be used to detect valid missing ids. 2. What is "valid missing entity"? 3. What is "valid missing id"? The (A) point was about finding entities without ';' ending. These entitites invalidate the XML document. After the XML document is fixed, there only remain valid stuff, and so the valid word in these names. They are a bit misleading, sure :) As I said before, I don't have nsgmls, so my missing-entities.ent is empty. But validation process goes just fine with cmd> xmllint.exe --noent --noout --valid manual.xml It might be close to perfect in the English tree, but remember we have a lot of translations, some of them having quite inexperienced team members. except for one thing with Zend API: element link: validity error : IDREF attribute linkend references an unknown ID "zend" But it can be fixed by replacing with &zend; entity, which contents will depend on if ZENDAPI is available. i.e. if ZENDAPI ZendAPI'>; else http://www.zend.com/zend/api.php";>ZendAPI'; endif Is there only one place linking to the Zend part? To my point of view there should not be any "missing valid" entries. There should not be, but there could be. Like I might add a link with &url.google;, but I forget to add this to the global entity file. Now I will not broke the build with this, but only that single link. If we remove the automatic missing entity/id creation, it becomes much easier (again) to break the build. This process is used to prevent the readers from suffering from errors made by authors/translators. More probably, that these "missing valid" will transform into interfaces for linking external documentation, so php hacks aren't good. No these are not always things linking to external docs. Most of the time, these are mispelled entity/id names, entity references, for which the actual added entities are forgotten, or existing documentation becoming broken due to id/entity name changes elsewhere. Goba
[PHP-DOC] RFC/xml_validation
Hello, [EMAIL PROTECTED] I've tried to make validation check on my WIN system without cygwin, jade and nsgmls and found some strange things about PHPDOC build system. I'll be glad if somebody could read this and answer my questions. =) RFC/xml_validation seems to be outdated. I'll quote it here for convenience. > xml validation with xmllint >[PROBLEM] >nsgmls aka "make test" does not detect entity usage without >trailing ';', either add additional checks or switch to a >different, more XML-specific validator. > >[SOLUTION] >xmllint form libxml package. xlstproc form the same package seems to be >XLST processor of choice. The english version of the enhanced chm manual >is produced by xsltproc. It seems a good idea to use programms out aof the >same package. > >[TESTRESULTS] >xmllint detects entity usage without trailing ';', also missing ids, >entities and double usage of IDs. > >xmllint needs to be run several times. > >(A) The first run should be used to detect wrong entities, without trailing ; >This errors should be fixed on the fly with a php script. > >(B) The second run should be used to detect valid missing entities. > >(c) The third run should be used to detect valid missing ids. > >Multiple runs of xmllint seems to be necessary. As long as wrong entities >(without trailing ;) exists, the error output is not usable to create valid >missing entities. Also is seems there is no way to convince convince xmllint >to report errors for missing entities and missing IDREFS in the same run. > >[POSSIBLE SOLUTIONS] >(1) long time: > Processing the manual with xsltproc relies on valid entities. Therefore it's > mandatory to ensure valid entities in all lang modules. > > - We need a script to catch wrong entities from the first run of xmllint, which > corrects them on the fly. > > - We need a script to produce missing-entities.ent and missing-ids.xml > > - Makefile.in and configure.in adjustments: > (a) detect/check for xmllint. > (b) include the above mentioned scripts in the build system > > (2) short time: > Use xmllint to check for non valid entities only. > > - Makefile.in and configure.in adjustments as above (1a) > - missing-entities and missing-ids are produced through existing mechanisms. > - additional make target for xmllint to check for wrong entities. > >Feb 10 2003: betz > >build system adjusted to detect xmllint >additional support for win, with the possibilty to use >phpdoc-tools/libxml for xslt and xmllint, rather than the >cygwin versions. > >A first script to create missing-entities.ent and missing-ids.xml >from xmllint output can be found in scripts/test_missting-entities.php.in > > Testing was done with libxml 20430 and 20502 1. Is the problem with missing ; still in place? Xmllint does the job pretty well, but is it really necessary to include additional PHP layer for processing xmllint messages? Every editor's highlightning engine can point out missing ; in xml entity, so I doubt there are many such errors. > (B) The second run should be used to detect valid missing entities. > (c) The third run should be used to detect valid missing ids. 2. What is "valid missing entity"? 3. What is "valid missing id"? As I said before, I don't have nsgmls, so my missing-entities.ent is empty. But validation process goes just fine with cmd> xmllint.exe --noent --noout --valid manual.xml except for one thing with Zend API: >element link: validity error : IDREF attribute linkend references an >unknown ID "zend" But it can be fixed by replacing with &zend; entity, which contents will depend on if ZENDAPI is available. i.e. if ZENDAPI ZendAPI'>; else http://www.zend.com/zend/api.php";>ZendAPI'; endif To my point of view there should not be any "missing valid" entries. More probably, that these "missing valid" will transform into interfaces for linking external documentation, so php hacks aren't good. I can't see the reasons for missing-entities no more. Perhaps I missed something so I'd like to know if I'm wrong. tnx, t -- --[ http://wiki.phpdoc.info/DocLinks ]--
Re: [PHP-DOC] RFC: documenting Object aggregation functions
--- Gabor Hojtsy <[EMAIL PROTECTED]> wrote: [...snip...] > &reference.objaggregation.functions.aggregation; > > So use the dirnames, and the filename without the > extension at the end. Your sample was not correct, > as you used "objaggregations" and not > "objaggregation" > as you pointed out the directory neme above. Also > you use "function" instead of "functions" which > is the correct dirname. Use dir and file names ;) Yep, I should've copy pasted instead of typing from memory ;-) [..snip..] > > 4) After I am done, which files should I modify so it > > will be include the next time the manual is > rebuilt? > > Add your reference entity to manual.xml.in, and so > from > then the doc will be included. If you don't do this, > it will be discarded. So you can commit anything, as > long > as it is not wired into manual.xml.in, it won't > appear. Will start adding documentation, but will not add it to manual.xml.in yet, until all discussions on object aggregation (which btw are compiled by default when configuring PHP 4.2.0) are resolved in php-dev as Derick mentioned (I thought they had finished, I will check the php-dev list again later today) > Your reference entity will be: > &reference.objaggregation.reference; = --- Jesus M. Castagnetto <[EMAIL PROTECTED]> __ Do You Yahoo!? Yahoo! Health - your guide to health and wellness http://health.yahoo.com
Re: [PHP-DOC] RFC: documenting Object aggregation functions
On Mon, 29 Apr 2002, Jesus M. Castagnetto wrote: > I am documenting the new object aggregation functions, > and before I add it to the CVS tree, I would like to > ask some questions: I would wait with documenting this until all discussions are done on it. regards, Derick > > 1) I am using en/reference/objaggregation for the > functions, is that OK? (got all the appropriate files > there) > > 2) Consistent w/ (1), all function entities are named > &reference.objaggregations.function.aggregation;, etc. > So if there is a better naming convention for the > object aggregation, let me know so I'll change those. > > 3) I am not including these functions in the classobj > section because they do not refer to object/class > properties, but to operations on objects. I would like > to see arguments for them being in classobj and not on > its own section, if any, before I am done w/ the > documentation. > > 4) After I am done, which files should I modify so it > will be include the next time the manual is rebuilt? > > > > = > --- Jesus M. Castagnetto <[EMAIL PROTECTED]> > > __ > Do You Yahoo!? > Yahoo! Health - your guide to health and wellness > http://health.yahoo.com > --- Did I help you? Consider a gift: http://www.amazon.co.uk/exec/obidos/registry/SLCB276UZU8B --- PHP: Scripting the Web - [EMAIL PROTECTED] All your branches are belong to me! SRM: Script Running Machine - www.vl-srm.net ---
Re: [PHP-DOC] RFC: documenting Object aggregation functions
> 1) I am using en/reference/objaggregation for the > functions, is that OK? (got all the appropriate files > there) Seems ok. I don't of it there is a better name for the aggregate extension. > 2) Consistent w/ (1), all function entities are named > &reference.objaggregations.function.aggregation;, etc. > So if there is a better naming convention for the > object aggregation, let me know so I'll change those. &reference.objaggregation.functions.aggregation; So use the dirnames, and the filename without the extension at the end. Your sample was not correct, as you used "objaggregations" and not "objaggregation" as you pointed out the directory neme above. Also you use "function" instead of "functions" which is the correct dirname. Use dir and file names ;) > 3) I am not including these functions in the classobj > section because they do not refer to object/class > properties, but to operations on objects. I would like > to see arguments for them being in classobj and not on > its own section, if any, before I am done w/ the > documentation. You can add see alsos to the classobj section afterwards. > 4) After I am done, which files should I modify so it > will be include the next time the manual is rebuilt? Add your reference entity to manual.xml.in, and so from then the doc will be included. If you don't do this, it will be discarded. So you can commit anything, as long as it is not wired into manual.xml.in, it won't appear. Your reference entity will be: &reference.objaggregation.reference; Goba
[PHP-DOC] RFC: documenting Object aggregation functions
I am documenting the new object aggregation functions, and before I add it to the CVS tree, I would like to ask some questions: 1) I am using en/reference/objaggregation for the functions, is that OK? (got all the appropriate files there) 2) Consistent w/ (1), all function entities are named &reference.objaggregations.function.aggregation;, etc. So if there is a better naming convention for the object aggregation, let me know so I'll change those. 3) I am not including these functions in the classobj section because they do not refer to object/class properties, but to operations on objects. I would like to see arguments for them being in classobj and not on its own section, if any, before I am done w/ the documentation. 4) After I am done, which files should I modify so it will be include the next time the manual is rebuilt? = --- Jesus M. Castagnetto <[EMAIL PROTECTED]> __ Do You Yahoo!? Yahoo! Health - your guide to health and wellness http://health.yahoo.com
Re: [PHP-DOC] /RFC
> IMHO this belongs to an appendix. Just make a warning on top, that it > is a) work in progress and so b) not worth translating yet. good idea
Re: [PHP-DOC] /RFC
Hi, On Wed, 13 Mar 2002 20:18:26 + (GMT) Philip Olson <[EMAIL PROTECTED]> wrote: > Is the RFC directory an okay place to put > work-in-progress goodies? For example, I want > to start (not finish :) a list of differences > of windows/*nix for PHP users to consider. IMHO this belongs to an appendix. Just make a warning on top, that it is a) work in progress and so b) not worth translating yet. Otherwise I have no objextions of having this in. Jan -- Q: Thank Jan? A: http://geschenke.an.dasmoped.net/
[PHP-DOC] /RFC
Hello, Is the RFC directory an okay place to put work-in-progress goodies? For example, I want to start (not finish :) a list of differences of windows/*nix for PHP users to consider. See bug #13321 for more details on this particular matter. Regards, Philip
Re: [PHP-DOC] RFC: Function Reference numbering in table of contents
> I'd like to change the numbering for s from roman to arabic > in the DSSSL stylesheets as i think that most readers are not that > familiar with roman numbers that they can decode eg. XLVIII as 48 > *and* roman numbers screw up the indentation in the TOC +1 The CHM scripts also need some modifications, in case you do this change, but these modifications are minor, so feel free to go on with the change :) Goba
[PHP-DOC] RFC: Function Reference numbering in table of contents
I'd like to change the numbering for s from roman to arabic in the DSSSL stylesheets as i think that most readers are not that familiar with roman numbers that they can decode eg. XLVIII as 48 *and* roman numbers screw up the indentation in the TOC [...] XLVIII. LDAP functions XLIX. Mail functions L. mailparse functions [...] it's a bit of a dirty hack as the numbering schemes are made language dependant in the modular stylesheets, but from what i have seen it is defined identical in every localized version i looked at any objections? -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] RFC
On Sat, 20 Oct 2001, Jirka Kosek wrote: > If you want to customize DTD it is always better to create customization > layer than to directly edit existing DTD. With this approach it is much > more easy to upgrade to new version DocBook which is used as a base for > your DTD. The customization DTD might look like: > > >'/path/to/local/copy/of/docbookx.dtd'> > %docbook; > paramdef)+))> > > > > In PHPBook documents you then would use this DTD instead of standard > DocBook DTD. Thanks. I never understood that it's so easy... > I think that change to DocBook DTD which you propose would be useful in > general. I suggest you to post this request as RFE for DocBook DTD at > the sourceforge pages. DocBook Technical Commitee has meatings each > month, so they should discuss it quite early. Done. -- Jouni
Re: [PHP-DOC] RFC
Hartmut Holzgraefe wrote: > > Jouni Ahto wrote: > > > Maybe it should be the time to find out what the current DTD actually is, > > and what it allows us to do? > > very good point! > (i was always refereing to "the book" which is for V3.1.x AFAIR) New version of TDG has actualised reference part for DocBook 4.1.2: http://www.docbook.org/tdg/en/html/docbook.html - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] RFC
On Fri, 19 Oct 2001, Hartmut Holzgraefe wrote: > Jouni Ahto wrote: > > > Maybe it should be the time to find out what the current DTD actually is, > > and what it allows us to do? > > > very good point! > (i was always refereing to "the book" which is for V3.1.x AFAIR) Besides, even if there's a clear need to change something, there's always the possibility of getting it accepted in the official version. See http://www.docbook.org/rfe/index.html http://sourceforge.net/tracker/?atid=384107&group_id=21935&func=browse -- Jouni
Re: [PHP-DOC] RFC
Jouni Ahto wrote: > I really like the part 'Maybe its time to get invloved [typos not fixed] > into the DocBook project itself, [...]' (Jirka actually is doing exactly > that). If DocBook can't satisfy a programming projects' needs, someone is > not modeling something the right way. Currently, I refuse to have any > opinions about whether it's us or the team that defines DocBook. There is a standard way to request new feature for DocBook. You can submit new request at: https://sourceforge.net/tracker/?atid=384107&group_id=21935&func=browse But note that DocBook process is quite slow. Changes in DTD must be announced at least one major version before they are really implemented. So proposalf for something wouldn't be part of DocBook before version 6.0 (I don't think that this version would be published earlier than two years from now). So if there is a realy strong need for some new elements or small change in content models, customizing DTD is only way to do it now and in near future. Jirka - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] RFC
Hojtsy Gabor wrote: > As Jirka said, as long as they use the DocBook DTDs > from the phpdoc repositories dbxml directory, they can > use tags added there. For other tools not dependant > on this directory, there would be much-much more > problems. There are some (IMHO not so elegant) solutions I think that all tools are using DTD in dbxml directory because manual.xml starts with rather strange DOCTYPE: http://www.kosek.cz
Re: [PHP-DOC] RFC
Jouni Ahto wrote: > Maybe it should be the time to find out what the current DTD actually is, > and what it allows us to do? very good point! (i was always refereing to "the book" which is for V3.1.x AFAIR)
Re: [PHP-DOC] RFC
>"./dbxml/docbookx.dtd" [... etc > > > DocBook XML 4.1.2 is the current XML version of DocBook. There are no > official XML versions of DocBook prior to V4.0. > > Maybe it should be the time to find out what the current DTD actually is, > and what it allows us to do? If we use 4.1.2 the official PUBLIC name for it is: -//OASIS//DTD DocBook XML V4.1.2//EN As projected in docbook.cat in the 4.1.2 package. So it is somewhat different than any other PUBLIC names, or DTDs we use. What a mess discovered! :) Goba
Re: [PHP-DOC] RFC
Hojtsy Gabor wrote: > These are problems that should be discussed. thats exactly the reason for me writing the PDF almost everything i mention in there has already been talked about on this list in some way without much work going on on it so i tried to summarize the identified problems and the possible solutions > So reworded: using namespaces to define tags, and use them > along DocBook tags. This is exaclty not extending DocBook, > but defining a DTD for our custom elements and use those > two DTDs (DocBook and PHPDoc) side-by-side. this topic came up after i had finished my first draft so it is not mentioned yet, but it definetly should be in there > Although I am __not__ speaking of extending DocBook, > there is a chapter about "Customizing DocBook", in > "DocBook: The definitive Guide". This customizing is what > Jirka is talking about. So for DocBook it is allowed. if we wouldn't mind cutting us off of other DocBook aware environments we could customize whatever we want we distribute the DTD anyway and the extensibility of the modular stylesheets allow as much costomization as we want to have we would have to call it something else but DocBook then, maybe PHPBook or so but as soon as we start changing the DTD it would probably become sort of pandoras box getting more and more a thing of its own ... > It is our job to decide, whether we choose customizing > or another way. I am against customizing DocBook this > way, so we are on the same side (and so Hartmut, as > I can see in this PDF). well, i tried to stay somehow neutral in this text, but customizing DocBook definetly comes for a price so the benefits we would gain from customizing do not compensate this for now IMHO
Re: [PHP-DOC] RFC
On Fri, 19 Oct 2001, Egon Schmid wrote: > From: "Hojtsy Gabor" <[EMAIL PROTECTED]> > > > So reworded: using namespaces to define tags, and use them > > along DocBook tags. This is exaclty not extending DocBook, > > but defining a DTD for our custom elements and use those > > two DTDs (DocBook and PHPDoc) side-by-side. > > This may be a misinformation. With tags I am always reffering to > elements. Please don´t touch them. Customization is another deal. Just to note: we are actually not using any official DocBook... manual.xml says: http://nwalsh.com/docbook/xml/ See COPYRIGHT for more information Please direct all questions and comments about this DTD to Norman Walsh, <[EMAIL PROTECTED]>. --> And then, when I went and poked around at http://www.docbook.org/, found this: XML DocBook XML 4.1.2 is the current XML version of DocBook. There are no official XML versions of DocBook prior to V4.0. Maybe it should be the time to find out what the current DTD actually is, and what it allows us to do? -- Jouni
Re: [PHP-DOC] RFC
> > So reworded: using namespaces to define tags, and use them > > along DocBook tags. This is exaclty not extending DocBook, > > but defining a DTD for our custom elements and use those > > two DTDs (DocBook and PHPDoc) side-by-side. > > This may be a misinformation. With tags I am always reffering to > elements. Please don´t touch them. Customization is another deal. The "Customizing DocBook" section also deals with adding tags, to the DocBook DTD as I can remember. http://www.docbook.org/tdg/en/html/ch05.html#ch05-addelem I do not want to touch DocBook elements, nor customize DocBook this way. I said we maybe can make another DTD, with only defining our own tags, we would like to use along side by side with DocBook. As Jirka mentioned, this would not be too good as a design decision, and the files can get impossible to validate, so this is not the way today. Then the only thing left for me is to use the role="" attribute for some custom usage. I do not want to modify the DocBook DTD. > > Although I am __not__ speaking of extending DocBook, > > there is a chapter about "Customizing DocBook", in > > "DocBook: The definitive Guide". This customizing is what > > Jirka is talking about. So for DocBook it is allowed. > > I know that :) But what will do the rest of the > committeres all over this world? As Jirka said, as long as they use the DocBook DTDs from the phpdoc repositories dbxml directory, they can use tags added there. For other tools not dependant on this directory, there would be much-much more problems. There are some (IMHO not so elegant) solutions posted by Jirka, and I can understand what he is saying, but I do not like adding tags this way. > > It is our job to decide, whether we choose customizing > > or another way. I am against customizing DocBook this > > way, so we are on the same side (and so Hartmut, as > > I can see in this PDF). > > What do you mean with "our"? The member of the "PHP Documentation Team". I use this wording as the people who are working in phpdoc, not just those listed on the frontpage. >From now on in this letter, I will use we as "you Egon and me". IMHO generally we are talking about the same things. We do not want to add tags to DocBook into the DTD, because several reasons. Some of these reasons are technical, some of these are just opinions. We do want to keep the XML files validateable. Goba
Re: [PHP-DOC] RFC
From: "Hojtsy Gabor" <[EMAIL PROTECTED]> > > > - the problem of entities (global.ent) as used in some old > > >translations and the main tree (deletes can make unbuildable > > >manuals) > > > > If you speak from old translations, so translate the other languages > > yourself. > > It is not that I would like to do all the translations. This > is a problem (like the translation of function files), that need > to be mentioned. This is not a negative grading of translators > working on some xml files. It is a fact, that this is a problem. > Please _do not_ see this as an attack. There are problems with those > entities and so with links to nonexistent XML ids. These are > problems that should be discussed. Oh I see, you have understand my problem. > > > - Extending docbook with namespaces. Also with drawbacks (design > > >validity testing and other problems mentioned by Jirka). > > > > I have said that extending DocBook is not allwowed. > > So reworded: using namespaces to define tags, and use them > along DocBook tags. This is exaclty not extending DocBook, > but defining a DTD for our custom elements and use those > two DTDs (DocBook and PHPDoc) side-by-side. This may be a misinformation. With tags I am always reffering to elements. Please don´t touch them. Customization is another deal. > Although I am __not__ speaking of extending DocBook, > there is a chapter about "Customizing DocBook", in > "DocBook: The definitive Guide". This customizing is what > Jirka is talking about. So for DocBook it is allowed. I know that :) But what will do the rest of the committeres all over this world? > It is our job to decide, whether we choose customizing > or another way. I am against customizing DocBook this > way, so we are on the same side (and so Hartmut, as > I can see in this PDF). What do you mean with "our"? -Egon
Re: [PHP-DOC] RFC
OK, it seems my words were not clear. So rewording. > > - the problem of entities (global.ent) as used in some old > >translations and the main tree (deletes can make unbuildable > >manuals) > > If you speak from old translations, so translate the other languages > yourself. It is not that I would like to do all the translations. This is a problem (like the translation of function files), that need to be mentioned. This is not a negative grading of translators working on some xml files. It is a fact, that this is a problem. Please _do not_ see this as an attack. There are problems with those entities and so with links to nonexistent XML ids. These are problems that should be discussed. > > - Extending docbook with namespaces. Also with drawbacks (design > >validity testing and other problems mentioned by Jirka). > > I have said that extending DocBook is not allwowed. So reworded: using namespaces to define tags, and use them along DocBook tags. This is exaclty not extending DocBook, but defining a DTD for our custom elements and use those two DTDs (DocBook and PHPDoc) side-by-side. Although I am __not__ speaking of extending DocBook, there is a chapter about "Customizing DocBook", in "DocBook: The definitive Guide". This customizing is what Jirka is talking about. So for DocBook it is allowed. It is our job to decide, whether we choose customizing or another way. I am against customizing DocBook this way, so we are on the same side (and so Hartmut, as I can see in this PDF). Goba
Re: [PHP-DOC] RFC
- Original Message - From: "Hojtsy Gabor" <[EMAIL PROTECTED]> To: "Hartmut Holzgraefe" <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]> Sent: Friday, October 19, 2001 7:05 PM Subject: Re: [PHP-DOC] RFC > > i have just uploaded the draft for the 'beyond' part of my conference > > talk "The manual and beyond" to > > > >http://zugeschaut-und-mitgebaut.de/php/conference-talk.pdf > > > > comments & suggestions are highly appreciated :) > > You should speak about > > - the problem of entities (global.ent) as used in some old >translations and the main tree (deletes can make unbuildable manuals) If you speak from old translations, so translate the other languages yourself. > - Extending docbook with namespaces. Also with drawbacks (design >validity testing and other problems mentioned by Jirka). I have said that extending DocBook is not allwowed. > After reading the pdf through these things seemed to be > important. Maybe more will come into my mind in the future. I hope I can talk with Hartmut tomorrow about this PDF on our PHP user meeting in Stuttgart. -Egon
Re: [PHP-DOC] RFC
On Fri, 19 Oct 2001, Hartmut Holzgraefe wrote: > > i have just uploaded the draft for the 'beyond' part of my conference > talk "The manual and beyond" to > >http://zugeschaut-und-mitgebaut.de/php/conference-talk.pdf > > comments & suggestions are highly appreciated :) I really like the part 'Maybe its time to get invloved [typos not fixed] into the DocBook project itself, [...]' (Jirka actually is doing exactly that). If DocBook can't satisfy a programming projects' needs, someone is not modeling something the right way. Currently, I refuse to have any opinions about whether it's us or the team that defines DocBook. -- Jouni
Re: [PHP-DOC] RFC
> i have just uploaded the draft for the 'beyond' part of my conference > talk "The manual and beyond" to > >http://zugeschaut-und-mitgebaut.de/php/conference-talk.pdf > > comments & suggestions are highly appreciated :) You should speak about - the problem of entities (global.ent) as used in some old translations and the main tree (deletes can make unbuildable manuals) - Jouni suggested to split up installation.xml also, as it is a hube beast now, and it is impossible to start the translation and finish it in a reasonable time (the same as with function files, mixed language). That is the most huge part, and there are some semi-sections (eg. Servers- prefix of titles), which are ugly IMHO, but with the current system, we can't do anything. - Extending docbook with namespaces. Also with drawbacks (design validity testing and other problems mentioned by Jirka). After reading the pdf through these things seemed to be important. Maybe more will come into my mind in the future. Goba
[PHP-DOC] RFC
i have just uploaded the draft for the 'beyond' part of my conference talk "The manual and beyond" to http://zugeschaut-und-mitgebaut.de/php/conference-talk.pdf comments & suggestions are highly appreciated :) -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
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
Re: [PHP-DOC] RFC : [PHP-DOC] FAQ porting to the manual?
RE: [PHP-DOC] RFC : [PHP-DOC] FAQ porting to the manual?Would this not be
better suited by using ... blocks instead of
blocks? Since requires a tag, it doesn't quite work
so well as it is currently in cvs. What do you guys think?
Daniel
- Original Message -
From: Hojtsy Gabor
To: 'Damien Seguy' ; 'Hojtsy Gabor' ; 'PHP-Doc list'
Sent: Monday, July 09, 2001 5:19 AM
Subject: RE: [PHP-DOC] RFC : [PHP-DOC] FAQ porting to the manual?
>Create a new directory for FAQ (called "faq").
>All main FAQ entry get its own file
>("faq.general","faq.mailing-lists","faq.obtaining","faq.databases"...).
Right. Than it will be a new section in the manual, like PEAR.
>Each file has the following layout :
>
>
> Obtaining PHP
> Obtaining PHP
>
>
>
>This faq deals with how to obtains PHP, where, when
>and why (this may be an optionnal introduction, as usual.).
>
>
>
>
>
>Where can I obtain PHP?
>
>
>Description
>
>You can download PHP from any of the members of the
>PHP network of sites. These can be found at
>&url.php;.
>You can also use anonymous CVS to get the absolute latest
>version of the source. For more information, go to
>&url.php.cvs;.
>
>
>
>
Seems all right :)
>Most of the job will be bringing in all URL, and extracting HTML
>tag : nothing bad, due to since layout from Jim.
URL-s should go to another faqurls.ent file in the faq
directory, or should stay as is in the xml files. What do
you think?
Sorry for the HTML mail, I have set PLAIN TEXT mail
in my Outlook, but the server converts it to HTML...
Goba
Re: [PHP-DOC] RFC : [PHP-DOC] FAQ porting to the manual?
On Mon, Jul 09, 2001 at 12:02:01PM +0200, Damien Seguy wrote: > on 8/07/01 12:43, Hojtsy Gabor at [EMAIL PROTECTED] wrote: > > What is the news about $subj? > Here is the suggestion : > > Any XML guru can validate such a file (Egon?)? If I have time :) > I'll be glad to hear any opinion. I'll make the folder and at least > one file later, so as to have a first draft soon. I have no opinion. I´m looking for a new job. -Egon -- LinuxTag, Stuttgart, Germany: July 5-8 2001: http://www.linuxtag.de/ All known books about PHP and related books: http://php.net/books.php Concert Band of the University of Hohenheim: http://www.concert-band.de/ First and second bestselling book in German: http://www.php-buch.de/
RE: [PHP-DOC] RFC : [PHP-DOC] FAQ porting to the manual?
Title: RE: [PHP-DOC] RFC : [PHP-DOC] FAQ porting to the manual?
>Create a new directory for FAQ (called "faq").
>All main FAQ entry get its own file
>("faq.general","faq.mailing-lists","faq.obtaining","faq.databases"...).
Right. Than it will be a new section in the manual, like PEAR.
>Each file has the following layout :
>
>
> Obtaining PHP
> Obtaining PHP
>
>
>
> This faq deals with how to obtains PHP, where, when
> and why (this may be an optionnal introduction, as usual.).
>
>
>
>
>
> Where can I obtain PHP?
>
>
> Description
>
> You can download PHP from any of the members of the
> PHP network of sites. These can be found at
> &url.php;.
> You can also use anonymous CVS to get the absolute latest
> version of the source. For more information, go to
> &url.php.cvs;.
>
>
>
>
Seems all right :)
>Most of the job will be bringing in all URL, and extracting HTML
>tag : nothing bad, due to since layout from Jim.
URL-s should go to another faqurls.ent file in the faq
directory, or should stay as is in the xml files. What do
you think?
Sorry for the HTML mail, I have set PLAIN TEXT mail
in my Outlook, but the server converts it to HTML...
Goba
[PHP-DOC] RFC : [PHP-DOC] FAQ porting to the manual?
on 8/07/01 12:43, Hojtsy Gabor at [EMAIL PROTECTED] wrote:
Hi Goba,
> What is the news about $subj?
Here is the suggestion :
Create a new directory for FAQ (called "faq").
All main FAQ entry get its own file
("faq.general","faq.mailing-lists","faq.obtaining","faq.databases"...).
Each file has the following layout :
Obtaining PHP
Obtaining PHP
This faq deals with how to obtains PHP, where, when
and why (this may be an optionnal introduction, as usual.).
Where can I obtain PHP?
Description
You can download PHP from any of the members of the
PHP network of sites. These can be found at
&url.php;.
You can also use anonymous CVS to get the absolute latest
version of the source. For more information, go to
&url.php.cvs;.
Most of the job will be bringing in all URL, and extracting HTML
tag : nothing bad, due to since layout from Jim.
Any XML guru can validate such a file (Egon?)?
I'll be glad to hear any opinion. I'll make the folder and at least
one file later, so as to have a first draft soon.
Damien Seguy
NB : Thanks for proof-reading resources.xml.
Re: [PHP-DOC] RFC reserved.xml :
I think it would be useful to have them in a multi-column table layout to start with. Whether they are grouped by some means or not, it's a toss up. Some people have mentioned in the errata that NULL, echo, print, exit, die, endif, endforeach. Also, "this" isn't a keyword, $this is the special variable. Daniel - Original Message - From: "Damien Seguy" <[EMAIL PROTECTED]> To: "Daniel Beckham" <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]> Sent: Friday, July 06, 2001 4:03 AM Subject: [PHP-DOC] RFC reserved.xml : > on 6/07/01 3:48, Daniel Beckham at [EMAIL PROTECTED] wrote: > > Hi, > > >> The list of reserverd words itself is quite bogus by the way... It really > >> should be reviewed soon. > I did this first draft. The goal was to gather all special words from PHP, > besides function names. I ordered them alphabetically. This is basically the > whole point. > > I'll be happy to share any other opinions. > > Best regards, > Damien Seguy > >
[PHP-DOC] RFC reserved.xml :
on 6/07/01 3:48, Daniel Beckham at [EMAIL PROTECTED] wrote: Hi, >> The list of reserverd words itself is quite bogus by the way... It really >> should be reviewed soon. I did this first draft. The goal was to gather all special words from PHP, besides function names. I ordered them alphabetically. This is basically the whole point. I'll be happy to share any other opinions. Best regards, Damien Seguy
Re: [PHP-DOC] RFC: some language issues
> One the other hand, parameter/returned types need often updates (int -> > boolean), and the 'mixed' type is not always easy to understand. > That would make more sense to get some consistency on this point. > I'll try to make an in-depth survey of used types, so as to shape their use. Mixed should be discussed in the types section. We need to point out that it is not a type, just a used keyword in the doc, to refer to any type (or more than one type). Goba ... . . . . . Editor of the Hungarian PHP manual, Admin of the Hungarian PHP mirror
Re: [PHP-DOC] RFC: some language issues
> > RFC (Request for comments): > > - what's the preferred name for the boolean type? > > 'bool' or 'boolean'? > > Boolean > > > - what's the preferred name for the floating point type? > > 'double' or 'float'? > > I think that depends on the context. Technically it should be 'double', > but people don't necessarily know what 'double' means and in full > sentences I think you can use 'floating point' to discuss the type. > I think we should use the types used with settype() and gettype() functions. To be absolutely clear. Goba ... . . . . . Editor of the Hungarian PHP manual, Admin of the Hungarian PHP mirror
Re: [PHP-DOC] RFC: some language issues
Jeroen van Wolffelaar wrote: > > > done (after six hours of heavy DSSSL-Fu :( ) > > Great :) > > I'll keep that in mind, I won't make any more s to types then. it's not about the XML, my mind just wasn't up to interprete these strange error messages jade emmits by times ... the actual patch was some 20 lines after all > DSSSL-fu... does that mean that it needs a modification of Norman's > styles? Or can it be applied without a problem in the phpdocs? see phpdoc/html-common.dsl you can overwrite any behaviour from the original stylesheets as long as you do not have to change the DTD, too -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] RFC: some language issues
on 16/05/01 20:33, Jeroen at [EMAIL PROTECTED] wrote: >>> - what's the preferred name for the boolean type? >>> 'bool' or 'boolean'? >> >> Boolean > > But bool in func-defs, I read in php.dev > And I meant in func-defs, because the 'real' word is - of course - boolean. > IMHO, I finally think this is not a real issue. boolean are pretty common in computing science, and I can't think of anyone not understanding bool. This stands for int/integer too. This way, I agree with Egon, and the shorter the better, this 'real' word don't add much value. However, I mostly used boolean in French version, and bool in English. No one ever complained about it. One the other hand, parameter/returned types need often updates (int -> boolean), and the 'mixed' type is not always easy to understand. That would make more sense to get some consistency on this point. I'll try to make an in-depth survey of used types, so as to shape their use. My few 0.02 centimes (about 0.003 Eur). Damien Seguy.
Re: [PHP-DOC] RFC: some language issues
> > - what's the preferred name for the boolean type? > > 'bool' or 'boolean'? > > Boolean But bool in func-defs, I read in php.dev And I meant in func-defs, because the 'real' word is - of course - boolean. > > - what's the preferred name for the floating point type? > > 'double' or 'float'? > > I think that depends on the context. Technically it should be 'double', > but people don't necessarily know what 'double' means and in full > sentences I think you can use 'floating point' to discuss the type. double refers to double precision, as opposed to float, which is single-precision. since php doesn't have different floating point types (to keep it easy), you could argue that float is better, since it is just a floating point. Compare to integer: in fact, it is a long! (but since php doesn't have byte,short,int, AND long, we just call it integer, or int, because that is the REAL name. Problem: gettype now returns double... and changing that could break code (although is_double should have been used there, and that function you can keep having as an alias) Conclusion: IMO float would be better... it is the general name of that TYPE of variable. > > > - Can it be made that string etc will > > automagically be rendered as a hyperlink to > > language.types.string etc? Just like ... > > Probably > > > - language.types is such an important and large section, > > that you'll cometimes get id's like > > language.types.integer.casting.from-boolean, > > what about renaming all language.types.* to types.*? > > or type.*? > > No opinion on this one. > > -Rasmus > Jeroen
Re: [PHP-DOC] RFC: some language issues
> RFC (Request for comments): > - what's the preferred name for the boolean type? > 'bool' or 'boolean'? Boolean > - what's the preferred name for the floating point type? > 'double' or 'float'? I think that depends on the context. Technically it should be 'double', but people don't necessarily know what 'double' means and in full sentences I think you can use 'floating point' to discuss the type. > - Can it be made that string etc will > automagically be rendered as a hyperlink to > language.types.string etc? Just like ... Probably > - language.types is such an important and large section, > that you'll cometimes get id's like > language.types.integer.casting.from-boolean, > what about renaming all language.types.* to types.*? > or type.*? No opinion on this one. -Rasmus
[PHP-DOC] RFC: some language issues
Hi, RFC (Request for comments): - what's the preferred name for the boolean type? 'bool' or 'boolean'? - what's the preferred name for the floating point type? 'double' or 'float'? - Can it be made that string etc will automagically be rendered as a hyperlink to language.types.string etc? Just like ... - language.types is such an important and large section, that you'll cometimes get id's like language.types.integer.casting.from-boolean, what about renaming all language.types.* to types.*? or type.*? Greetings, Jeroen
