Re: [PHP-DOC] developers manual and users manual
May I suggest you just duplicate the entire current manual structures for the new manual(s) and don't add any translation directories. That way when someone decides they have to have the new manual in their native language you don't have to work so hard to support it. They will eventually... Uh, it's not that easy. We have separate mailing lists for translations and separate CVS modules for every translation. Well, if we duplicate all these, we get a huge mess... If we push all users manual content one subdir down and make a new subdir for developers manual content (in all phpdoc modules), then we get a huge mess (there will be no CVS history for files, updates will get even harder). Actually I don't think so that someone can write a PHP extension if he even don't know English... PEAR, PHP-GTK, TSRM and other projects also copied the build system, so we have quite differently evolved build systems everywhere. Copying the build system does not help IMHO, but increases confusion, as different projects modify that initially same build system to their needs in different ways, so you cannot just jump in and work with another build system. For example the PEAR system uses XSL sheets exclusively, while we are just in the testing phase of converting to XSL sheets, and still use DSSSL ones, which require completely different conversion tools... Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
--- Gabor Hojtsy [EMAIL PROTECTED] wrote: May I suggest you just duplicate the entire current manual structures for the new manual(s) and don't add any translation directories. That way when someone decides they have to have the new manual in their native language you don't have to work so hard to support it. They will eventually... Uh, it's not that easy. We have separate mailing lists for translations and separate CVS modules for every translation. Well, if we duplicate all these, we get a huge mess... If we push all users manual content one subdir down and make a new subdir for developers manual content (in all phpdoc modules), then we get a huge mess (there will be no CVS history for files, updates will get even harder). Yep, It might be simpler to move the chapters/appendices that will make the Devloper's manual (or whatever name we decide) to its own top level CVS dir tree, and then handle that part alone. As that is the (relatively) newer part of the current manual, it will generate the less amount of damage/problems. Now, separating the rest into a Language and a Function references will be hairier and short of splitting them and then hand-fixing the CVS files, I have no simple ideas/solutions to propose. Actually I don't think so that someone can write a PHP extension if he even don't know English... Agree there. If we separate the Howto, Zend engine, streams, etc. into its own 'phpdoc-dev' (or something like that), then it will be clear that is not something to be translated. PEAR, PHP-GTK, TSRM and other projects also copied the build system, so we have quite differently evolved build systems everywhere. Copying the build system does not help IMHO, but increases confusion, as different projects modify that initially same build system to their needs in different ways, so you cannot just jump in and work with another build system. Indeed, in particular in PEAR we are working towards allowing simpler generation of class documentations. As we are already using javadoc-style comments in the code, we could generate the DocBook prototypes programatically, the PEAR::PHPDoc tool is being modified for that purpose. Also there are some OpenOffice - DocBook filters being developed to simplify the task of writing the tutorials on how to use the packages, etc. For example the PEAR system uses XSL sheets exclusively, while we are just in the testing phase of converting to XSL sheets, and still use DSSSL ones, which require completely different conversion tools... Goba = --- Jesus M. Castagnetto [EMAIL PROTECTED] __ Do You Yahoo!? HotJobs - Search Thousands of New Jobs http://www.hotjobs.com -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
Hi, On Mon, Aug 12, 2002 at 01:20:03AM +0200, Friedhelm Betz wrote: +1 goba for his suggestion of splitting +1 (wasn't that discussed during the doc meeting?) +1 jesus for PHP Users Manual and a PHP Developers Manual -1 too ambigous. -1 goba and jome for PHP Inner Workings Manual sounds horrible in my ears ;-) Can we have the PHP Manual and the PHP Internals ? Jan -- Q: Thank Jan? A: http://geschenke.an.dasmoped.net/ Got an old and spare laptop? Please send me a mail. -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
+1 goba for his suggestion of splitting +1 (wasn't that discussed during the doc meeting?) We talked about something like this, but putting up a build system without translation support is completely different than thinking about translations. So the real question now is if everybody agrees that translation support is not needed for PHP Internals Manual, much like the phpdoc howto and other docs... +1 jesus for PHP Users Manual and a PHP Developers Manual -1 too ambigous. -1 goba and jome for PHP Inner Workings Manual sounds horrible in my ears ;-) Can we have the PHP Manual and the PHP Internals ? Sounds good ;) Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
--- Gabor Hojtsy [EMAIL PROTECTED] wrote: +1 @goba for his suggestion of splitting +1 (wasn't that discussed during the doc meeting?) We talked about something like this, but putting up a build system without translation support is completely different than thinking about translations. So the real question now is if everybody agrees that translation support is not needed for PHP Internals Manual, much like the phpdoc howto and other docs... +1 @jesus for PHP Users Manual and a PHP Developers Manual -1 too ambigous. Hmm, ambiguous? Maybe I am missing something and Developer == User in a non-English and non-Spanish European/Slavic/Oriental language? In any case, if you really want to be clear on what you mean, we should have the following: 1) Language Reference 2) Functions Reference (aka Library Reference) 3) PHP Internals and Extension Development i.e. a model like the one for Python's documentation which, in case you missed it in my previous msg, is at the URL: http://www.python.org/doc/ In this way, (1) can be an intro to the language, configuration, and include the migration bits from the appendices. Manual (2) will contain the functions section of the current manual, with the added benefit that we will be able to group the functions/extensions w/o having to recourse to making an extension to DocBook, by merely using the 'part' tags to structure the groups. The manual (3) will not need translation, as is intended for people writing C extensions or tinkering w/ the interpreter itself. Of course, this will make thing a little more complicated initially, but will be easier from the manual building/maintainance point of view. The Function Reference changes more often than the others, so the manual generation schedule can be changed to reflect that. -1 @goba and @jome for PHP Inner Workings Manual sounds horrible in my ears ;-) Can we have the PHP Manual and the PHP Internals ? Sounds good ;) Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php = --- Jesus M. Castagnetto [EMAIL PROTECTED] __ Do You Yahoo!? HotJobs - Search Thousands of New Jobs http://www.hotjobs.com -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
Hmm, ambiguous? Maybe I am missing something and Developer == User in a non-English and non-Spanish European/Slavic/Oriental language? The problem is that a major part of our user base think that they develop IN PHP, so they are PHP developers... Just search for java developer or c developer in google, and you'll find sites for guys developing IN Java/C and not developing Java/C itself. So this is why Developers Manual may not be appropriate... In any case, if you really want to be clear on what you mean, we should have the following: 1) Language Reference 2) Functions Reference (aka Library Reference) 3) PHP Internals and Extension Development i.e. a model like the one for Python's documentation which, in case you missed it in my previous msg, is at the URL: http://www.python.org/doc/ Of course, this will make thing a little more complicated initially, but will be easier from the manual building/maintainance point of view. The Function Reference changes more often than the others, so the manual generation schedule can be changed to reflect that. I can see your point here, but this needs to be discussed widely, so we do not make big changes without knowing that we are doin the right thing (TM). Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
On Mon, 12 Aug 2002, Jesus M. Castagnetto wrote: In any case, if you really want to be clear on what you mean, we should have the following: 1) Language Reference 2) Functions Reference (aka Library Reference) 3) PHP Internals and Extension Development I like this division. This will allow development of more introductory material in a separate space from function documentation. -adam -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
At 12:22 PM 8/12/02 +0200, Gabor Hojtsy wrote: +1 goba for his suggestion of splitting +1 (wasn't that discussed during the doc meeting?) We talked about something like this, but putting up a build system without translation support is completely different than thinking about translations. So the real question now is if everybody agrees that translation support is not needed for PHP Internals Manual, much like the phpdoc howto and other docs... May I suggest you just duplicate the entire current manual structures for the new manual(s) and don't add any translation directories. That way when someone decides they have to have the new manual in their native language you don't have to work so hard to support it. They will eventually... Rick -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
At 03:40 AM 8/12/02 -0700, Jesus M. Castagnetto wrote: 1) Language Reference 2) Functions Reference (aka Library Reference) 3) PHP Internals and Extension Development fwiw +1 on this. -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
I think a split is a good idea though I think a name change could be confusing (don't know if that's what you're suggesting?). A lot of web developers probably considers themselves PHP developers and will go to PHP Developers manual even though they're looking for information which is in the other manual. (Just like the php-dev list receives e-mails from users asking about development _in_ php.) Well, I know about this PHP Developer problem... While this is not a problem for eg. MySQL, where it's clear who is a user and a developer, it's not that simple for PHP... Maybe we can leave the PHP Manual as it is know and just name that new manual with a good title, such as PHP Inner Workings Manual or something like that just to avoid confusion... Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
Well, I know about this PHP Developer problem... While this is not a problem for eg. MySQL, where it's clear who is a user and a developer, it's not that simple for PHP... Maybe we can leave the PHP Manual as it is know and just name that new manual with a good title, such as PHP Inner Workings Manual or something like that just to avoid confusion... Sounds like a good idea. Regards, Jome -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
Not sure if people using PHP for development will be confused, in particular if we have a: PHP Users Manual and a PHP Developers Manual Other software projects use different approaches, e.g. Python (http://www.python.org/doc/) where the different bits are separated, whereas the PostgreSQL has 2 top level sections User's Lounge and Developer's Corner, perhaps a separation like that can clarify who are the target audience for the docs. --- Jome [EMAIL PROTECTED] wrote: Well, I know about this PHP Developer problem... While this is not a problem for eg. MySQL, where it's clear who is a user and a developer, it's not that simple for PHP... Maybe we can leave the PHP Manual as it is know and just name that new manual with a good title, such as PHP Inner Workings Manual or something like that just to avoid confusion... Sounds like a good idea. Regards, Jome -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php = --- Jesus M. Castagnetto [EMAIL PROTECTED] __ Do You Yahoo!? HotJobs - Search Thousands of New Jobs http://www.hotjobs.com -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
Hi all, Monday, August 12, 2002, 12:24:52 AM, you wrote: Not sure if people using PHP for development will be confused, in particular if we have a: PHP Users Manual and a PHP Developers Manual Other software projects use different approaches, e.g. Python (http://www.python.org/doc/) where the different bits are separated, whereas the PostgreSQL has 2 top level sections User's Lounge and Developer's Corner, perhaps a separation like that can clarify who are the target audience for the docs. +1 @goba for his suggestion of splitting +1 @jesus for PHP Users Manual and a PHP Developers Manual -1 @goba and @jome for PHP Inner Workings Manual sounds horrible in my ears ;-) --- Jome [EMAIL PROTECTED] wrote: Well, I know about this PHP Developer problem... While this is not a problem for eg. MySQL, where it's clear who is a user and a developer, it's not that simple for PHP... Maybe we can leave the PHP Manual as it is know and just name that new manual with a good title, such as PHP Inner Workings Manual or something like that just to avoid confusion... Sounds like a good idea. Regards, Jome Friedhelm -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] developers manual and users manual
+1 for splitting -1 for 'PHP Developers' Manual' vs 'PHP Users' Manual', there is a huge amount of confusion about this as we all know. Other software projects don't generally have the same issue with this .. 'PHP Sourcerers' Manual' vs 'PHP Manual'? - we need something _that_ obvious IMHO. Not sure if people using PHP for development will be confused, in particular if we have a: PHP Users Manual and a PHP Developers Manual Other software projects use different approaches, e.g. Python (http://www.python.org/doc/) where the different bits are separated, whereas the PostgreSQL has 2 top level sections User's Lounge and Developer's Corner, perhaps a separation like that can clarify who are the target audience for the docs. -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
