Re: [PHP-DOC] See also refsects?
In mysqli-client-encoding.xml, I ran into that : See also mysqli_client_encoding. mysqli_real_escape_string. Is that a policy for see also sections? Nope, should be: and . or: , and . So there is no problem if you put it into a refsect (it was actually a plan to do docwise, just noone had the time to do it). Goba
Re: [PHP-DOC] See also refsects?
On Tue, 30 Mar 2004, Damien Seguy wrote: > Hi guys, > > In mysqli-client-encoding.xml, I ran into that : > > > See also > > mysqli_client_encoding. > mysqli_real_escape_string. > > > > Is that a policy for see also sections? Nope, should be: and . or: , and . regards, Derick
Re: [PHP-DOC] see also serialize/unserialize
Just a quick remark. I really think that the manual sections on 'implode' and 'explode' should refer to 'serialize' and 'unserialize' in their see also lists. Otherwise you have the best online manual I know. Keep up the good work. Regards, Oscar Hi Oscar, I saw your note this morning (http://news.php.net/article.php?group=php.notes&article=51892). I've deleted it because there was already a note saying the same thing posted by "kj at mendosus dot org". I (or someone else) will have a look and a note will be integrated. Thank you for helping us making the manual much better ;) Regards, Mehdi -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
Why our own tag for see also would be better? - 98% [approx] of see alsos are not that exoticaly worded, as you have done in your example - with our own tags, no translation would be needed for this part - there will be an ability to automatically recognize see also parts, which can seriously help in presentation, and automatic discovery [eg. we can check what parts are better connected in the manual, and what needs more attention] i remember that we have thought about it before (when someone insisted that in english a comma is needed before the 'and' here ...) ... and AFAIR there are DocBook tags for lists or enumerations that we could use with setting a special role attribute ... i even did some experimental stuff with this back then but somehow this got lost on the way ... i'll try to remember what i did back then ... As far as I can remember, it was some bloated XML syntax [ie. too much markup]. But let is come up again, we have this on the docmeeting agenda :) Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
Ford, Mike [LSS] wrote: That someone was wrong -- at least according to how I had it drummed into me at school lo! these many years ago. it depents on what style guide you read (and maybe which continent you are on?) the Chicago Manual of Style says ", and", the Minnesota Universty Styleguide says no ... -- Hartmut Holzgraefe <[EMAIL PROTECTED]> -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
RE: [PHP-DOC] see also
> -Original Message- > From: Hartmut Holzgraefe [mailto:[EMAIL PROTECTED] > Sent: 19 June 2003 20:35 > > Gabor Hojtsy wrote: > >> Adding our own things to docbook is not a good idea, as it > will need > >> more modifications to our stylesheets. Also, it will make it less > >> flexible in cases like: > > > Why our own tag for see also would be better? > > > > - 98% [approx] of see alsos are not that exoticaly worded, as you > >have done in your example > > - with our own tags, no translation would be needed for this part > > - there will be an ability to automatically recognize see > also parts, > >which can seriously help in presentation, and automatic discovery > >[eg. we can check what parts are better connected in the manual, > >and what needs more attention] > > i remember that we have thought about it before (when someone insisted > that in english a comma is needed before the 'and' here ...) ... That someone was wrong -- at least according to how I had it drummed into me at school lo! these many years ago. Of course, there are exceptions to the rule (e.g. "I shop at Tesco, Marks and Spencer, and Asda"), but I would say the elements in a see-also list are short enough and unambiguous enough not to warrant a comma before the "and". It's not definitively wrong, but it's definitely not necessary. Cheers! Mike - Mike Ford, Electronic Information Services Adviser, Learning Support Services, Learning & Information Services, JG125, James Graham Building, Leeds Metropolitan University, Beckett Park, LEEDS, LS6 3QS, United Kingdom Email: [EMAIL PROTECTED] Tel: +44 113 283 2600 extn 4730 Fax: +44 113 283 3211 -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
'See also' is in the gentext language files, folks. It's supposed to be an entity. (and no, we don't use it either .. yet) - Original Message - From: "Hartmut Holzgraefe" <[EMAIL PROTECTED]> To: "Gabor Hojtsy" <[EMAIL PROTECTED]> Cc: "Derick Rethans" <[EMAIL PROTECTED]>; "Philip Olson" <[EMAIL PROTECTED]>; "Friedhelm Betz" <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]> Sent: Thursday, June 19, 2003 7:34 PM Subject: Re: [PHP-DOC] see also > Gabor Hojtsy wrote: > >> Adding our own things to docbook is not a good idea, as it will need > >> more modifications to our stylesheets. Also, it will make it less > >> flexible in cases like: > > > Why our own tag for see also would be better? > > > > - 98% [approx] of see alsos are not that exoticaly worded, as you > >have done in your example > > - with our own tags, no translation would be needed for this part > > - there will be an ability to automatically recognize see also parts, > >which can seriously help in presentation, and automatic discovery > >[eg. we can check what parts are better connected in the manual, > >and what needs more attention] > > i remember that we have thought about it before (when someone insisted > that in english a comma is needed before the 'and' here ...) ... > > and AFAIR there are DocBook tags for lists or enumerations that we > could use with setting a special role attribute ... i even did some > experimental stuff with this back then but somehow this got lost > on the way ... > > i'll try to remember what i did back then ... > > -- > Hartmut Holzgraefe <[EMAIL PROTECTED]> > > > -- > PHP Documentation Mailing List (http://www.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > > -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
Gabor Hojtsy wrote: Adding our own things to docbook is not a good idea, as it will need more modifications to our stylesheets. Also, it will make it less flexible in cases like: Why our own tag for see also would be better? - 98% [approx] of see alsos are not that exoticaly worded, as you have done in your example - with our own tags, no translation would be needed for this part - there will be an ability to automatically recognize see also parts, which can seriously help in presentation, and automatic discovery [eg. we can check what parts are better connected in the manual, and what needs more attention] i remember that we have thought about it before (when someone insisted that in english a comma is needed before the 'and' here ...) ... and AFAIR there are DocBook tags for lists or enumerations that we could use with setting a special role attribute ... i even did some experimental stuff with this back then but somehow this got lost on the way ... i'll try to remember what i did back then ... -- Hartmut Holzgraefe <[EMAIL PROTECTED]> -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
Adding our own things to docbook is not a good idea, as it will need more modifications to our stylesheets. Also, it will make it less flexible in cases like: See also: foo for an example and foo2 for more information on blah. I think we just should set a standard if we;'re going to add a : or not (I don't really care, as long as it is consistent). As I emphasized before, PHP-GTK docs uses a modified version of docbook without problems. Adding customizations to the XSL sheets is not a problem. As I have written in the agenda, I think that if we can move to "manageable" output generation methods [eg. XSLT or livedocs] then we can make this move. Why our own tag for see also would be better? - 98% [approx] of see alsos are not that exoticaly worded, as you have done in your example - with our own tags, no translation would be needed for this part - there will be an ability to automatically recognize see also parts, which can seriously help in presentation, and automatic discovery [eg. we can check what parts are better connected in the manual, and what needs more attention] OK I admit that the automatic discovery is a weak point, as our own see alsos are not that big plus for this... An example: mysql_close mysql_fetch_array mysql_fetch_row mysql_fetch_assoc That would render: | See also mysql_close, mysql_fetch_array, mysql_fetch_row, | and mysql_fetch_assoc. Note, that "See also", the commas and the "and" is autogenerated. This without translation will become: | Lásd még mysql_close, mysql_fetch_array, mysql_fetch_row | és mysql_fetch_assoc. For Hungarian. Note that we don't use a comma before the last "and". That still enables you to use a with more explanation if you want to, instead of adding a . Additionaly this will be very good for several output formats. CHM for example can place the see also links on top of the page in a dropdown menu, as it is in most windows programming help manuals. Note that I used the tag example, because is used in DocBook, just for a completely different purpose. Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
On Thursday 19 June 2003 19:48, Derick Rethans wrote: [...] > > I think we just should set a standard if we;'re going to add a : or not > (I don't really care, as long as it is consistent). I don't care either, the reason I asked was exactly that sometimes is written with and sometimes without colon. Friedhelm -- http://www.jungle-world.com/ -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
On Thu, 19 Jun 2003, Gabor Hojtsy wrote: > >>with or without : ? > >> > >>Deep in my mind I remember Dams changed a couple of see also's to be written > >>without : > > > > Officially it should be without. Hold off on any mass > > changes though until the doc meeting figures out the > > format for "See also" as rumor has it a new tag or > > similar will exist for them. > > I hope we will be able to add a new structural element for that. That > would help much in the rendering of the docs, as well as automatic > discovery. :) Adding our own things to docbook is not a good idea, as it will need more modifications to our stylesheets. Also, it will make it less flexible in cases like: See also: foo for an example and foo2 for more information on blah. I think we just should set a standard if we;'re going to add a : or not (I don't really care, as long as it is consistent). Derick -- "Interpreting what the GPL actually means is a job best left to those that read the future by examining animal entrails." - Derick Rethans http://derickrethans.nl/ International PHP Magazine http://php-mag.net/ - -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
with or without : ? Deep in my mind I remember Dams changed a couple of see also's to be written without : Officially it should be without. Hold off on any mass changes though until the doc meeting figures out the format for "See also" as rumor has it a new tag or similar will exist for them. I hope we will be able to add a new structural element for that. That would help much in the rendering of the docs, as well as automatic discovery. :) Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
On Thu, 19 Jun 2003, Friedhelm Betz wrote: > > with or without : ? > > Deep in my mind I remember Dams changed a couple of see also's to be written > without : Officially it should be without. Hold off on any mass changes though until the doc meeting figures out the format for "See also" as rumor has it a new tag or similar will exist for them. Regards, Philip -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] see also
> with or without : ? > > Deep in my mind I remember Dams changed a couple of see also's to be > written without : In the french translation we do like so : See also function1, function2, function3 and function4. Maybe it can be applied to the english documentation. Cheers, Mehdi -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] See also
Snipped proposed versions: > > > somefunc1 > somefunc2 > > > If we want a more list like construct, it's a bit more markup heavy: > > > > somefunc1 > > > somefunc2 > > What would be the advantage of using the list? The first one looks much nicer except one question, I assume the following will render fine: example Stream Functions Point is not only functions will be listed and we will have to be careful on how ',' and 'and' will look. I can't think of a good example but I know some places have things that won't fit nicely in this predefined mold. So, I guess they'll just have to be rewritten to fit which shouldn't be a big deal. Regards, Philip -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] See also
So would it be possible to do just array_filter array_walk And have a stylesheet add things like "See also", ",", "and" and "."? So that the actual format for the See also is totally consistent for every language? Dirkjan > Well, there is already a seealso tag in Docbook which is sadly for something > totally different purpose, so we should not use that. There were two > proposals > to use some list construct or to use that to enclose > see > also listings. That would also make the presentation of see also lists more > dynamic in the CHMs for example, which I would love to see ;) -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] See also
> So would it be possible to do just > > > array_filter > array_walk > > > And have a stylesheet add things like "See also", ",", "and" and "."? So > that the actual format for the See also is totally consistent for every > language? Something like this, yes. But with a "bit" more markup. DocBook does not allow us to have a inside a , so to make this fully DocBook compatible: somefunc1 somefunc2 Then this can be automatically rendered to start with See also, put a , between elements "and" before the last element (even depending on langauge preferences, as some languages don't use "and" there, like the Germans :). And a dot can be put at the end of course ;) If we want a more list like construct, it's a bit more markup heavy: somefunc1 somefunc2 But BTW we already have a proposal to change the DTD to have extension documentations grouped by some criteria. See /RFC/manual.xml.in and dtds/phpbook.dtd. The customizations are quite simple, and easy (and supported by DocBook). The only problem is that the customizations are not yet done on the style sheet side (DSSSL and XSLT), so the rendering is very dumb of that manual. And we have also not agreed on using a modified DocBook DTD, even as some other PHP projects use modified DocBook DTDs... Some guys used to have negative feelings about it... BTW more information on the DocBook format here: http://www.docbook.org/tdg/en/ Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] See also
So would it be possible to do just array_filter array_walk And have a stylesheet add things like "See also", ",", "and" and "."? So that the actual format for the See also is totally consistent for every language? Dirkjan > Well, there is already a seealso tag in Docbook which is sadly for something > totally different purpose, so we should not use that. There were two > proposals > to use some list construct or to use that to enclose > see > also listings. That would also make the presentation of see also lists more > dynamic in the CHMs for example, which I would love to see ;) -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] See also
> > (Sent this to goba only by accident) > > > > Maybe it might even be useful to have something like a "seealso.xml" which > > has like > > > > > > array_search > > > > > > Or something like that (this is probably not a useful structure)? This way, > > you can keep all of the See also separate from the function reference and > > closely together with other See also's, so that it is easy to organise > > clusters of related functions and people can quickly see which functions a > > function should be referring to... > > WOuld be nice, but it's not DocBook XML and we will need to make mods to > the DTD and stylesheets then. Well, there is already a seealso tag in Docbook which is sadly for something totally different purpose, so we should not use that. There were two proposals to use some list construct or to use that to enclose see also listings. That would also make the presentation of see also lists more dynamic in the CHMs for example, which I would love to see ;) BTW for your other idea to have separate XML files to store see also data, and link them from places, I think it would overly complicate the see also linking process, and much more customizations need to be made to the style sheets to check if a function tries to link with a see also to itself, so I don't think that putting see alsos out to their own files is a good idea... Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] See also
On Sat, 11 Jan 2003, Dirkjan Ochtman wrote: > (Sent this to goba only by accident) > > Maybe it might even be useful to have something like a "seealso.xml" which > has like > > > array_search > > > Or something like that (this is probably not a useful structure)? This way, > you can keep all of the See also separate from the function reference and > closely together with other See also's, so that it is easy to organise > clusters of related functions and people can quickly see which functions a > function should be referring to... WOuld be nice, but it's not DocBook XML and we will need to make mods to the DTD and stylesheets then. Derick -- - Derick Rethans http://derickrethans.nl/ PHP Magazine - PHP Magazine for Professionals http://php-mag.net/ - -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] See also in uniqid.xml
I can maybe see a "See Also" for rand() and *possibly* microtime(), but md5() should not be confused with unique ids. wrapping md5() around any of the aforementioned functions (including uniqid()) actually makes the resultant string LESS random, and LESS unique. -Pollita > I recommend a "See Also" in /reference/misc/functions/uniqid.xml to > md5() and rand() > > Thanks > Fernando Correa da Conceição > -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] See also
Hartmut Holzgraefe wrote: > i will not believe this until i have *seen* that eg. the parameter > list rendering for optional arguments comes out easier than it is > in DSSSL ;) > > from my rather limit XSLT experience it is easier to use on simple > problems but can become a complete nightmare on more challanging > tasks while DSSSL is overkill for simple tag replacements but has > the power of a 'real' extensible programming language after all Both are turing complete, so you can do anything in both of them. XSLT has much more easy to use query language (compare short XPath expressions with quite verbose code in DSSSL). On the other hand, XSLT doesn't hove some types -- e.g. lists which are very useful when impelmenting some task. This will change in XSLT2 as it comes with sequence data-type. -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
Lars Torben Wilson wrote: > Existing support for the DSSSL stylesheets may be more > comprehensive, but IMHO XSL is so much easier to work with that it's > worth the effort to move toward it. i will not believe this until i have *seen* that eg. the parameter list rendering for optional arguments comes out easier than it is in DSSSL ;) from my rather limit XSLT experience it is easier to use on simple problems but can become a complete nightmare on more challanging tasks while DSSSL is overkill for simple tag replacements but has the power of a 'real' extensible programming language after all (they are both LISPish in concepts anyway, although XLST tries to hide that by replacing the parentheses with more familiar looking s ;) -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
Egon Schmid wrote: > We use since 1997 The Chicago Manual of Style and now EOD. Where is this decision documented? Is it in the howto? NO! Is it in the README? NO! Is it in the list archive? The one i know of doesn't go back beyond 1999, so most likely: NO! the only useful reference regarding this was in a thread over a year ago, with a rather insightfull contribution from Ron Charma: http://marc.theaimsgroup.com/?l=phpdoc&m=97847158431357&w=2 so even if this decision was made back in '97 it isn't valid anymore as most of the current contributors can't even possibly know about it that doesn't mean we can't agree on using the CMoS, but we (the *current* maintainers and contributors) have to take this decision again *and* have to document it in the howto for the future to have it take effect even with the natural fluctuation in projects like these -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
> > I can devote some to do it, but is there anyone who wants to use XSL? > > When I asked same question year ago, almost noone respond. If there will > > be no usage of XSL, why to cutomize stylesheets? > > > > Jirka > > I do, I do! Existing support for the DSSSL stylesheets may be more > comprehensive, but IMHO XSL is so much easier to work with that it's > worth the effort to move toward it. Maybe it's just that the > parentheses scare me...:) PHP-GTK quys also use XSL style sheets exclusively to generate online HTML and downloadable docs from DocBook files. Goba
Re: [PHP-DOC] See also
Jirka Kosek wrote: > Hartmut Holzgraefe wrote: > > >>it's things like automatic linking and adding () for >>references in normal text, >> > > I thought that this I have hacked year ago. so you just found out how much i looked into the xsl files :) >>rendering optional parameters a bit more >>clever ... and ... and ... and ... >> > > I can devote some to do it, but is there anyone who wants to use XSL? > When I asked same question year ago, almost noone respond. If there will > be no usage of XSL, why to cutomize stylesheets? chicken/egg problem? no, realy, XSL tools and available documentation have improved since then, while on the DSSSL front nothing new happened e.g. saxon is already faster than jade when producing bightml, although it still loses on the multipage html yet (don't know about other XSLT processors yet) afaik print output isn't as good as with our current setup but with all the emerging problems (pushing TeX buffer sizes to their limit, rendering problems like we had with '--') and with even Sebastian Rahtz saying that the TeX backend to jade needs a complete redesing we seem to be better of at the XSL side in the near future -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
> > it's things like automatic linking and adding () for > > references in normal text, > > I thought that this I have hacked year ago. > > > rendering optional parameters a bit more > > clever ... and ... and ... and ... > > I can devote some to do it, but is there anyone who wants to use XSL? > When I asked same question year ago, almost noone respond. If there will > be no usage of XSL, why to cutomize stylesheets? Hartmut talked at the International PHP Conference about the manual, current system, and how it can be optimized. One of the points was to experiment with XSL stuff, because XSL is a more widely supported language than DSSSL, and it supports XML things like namespaces, and the like. More on XSL side is that it seems the PDF generation reached a point, where we are unable to handle limits in the generator software. Jim tested PDF generation with FOP, and it seemed to him, that it is quicker (although not all the customizations went through). Speed is another factor for HTML generation. Personaly I would like to see XSL instead of DSSSL, because XSL is naturally readeable than DSSSL, and there are many docs and tutorials for it on the net. Goba [one [EMAIL PROTECTED]]
Re: [PHP-DOC] See also
Jirka Kosek writes: > Hartmut Holzgraefe wrote: > > > it's things like automatic linking and adding () for > > references in normal text, > > I thought that this I have hacked year ago. > > > rendering optional parameters a bit more > > clever ... and ... and ... and ... > > I can devote some to do it, but is there anyone who wants to use XSL? > When I asked same question year ago, almost noone respond. If there will > be no usage of XSL, why to cutomize stylesheets? > > Jirka I do, I do! Existing support for the DSSSL stylesheets may be more comprehensive, but IMHO XSL is so much easier to work with that it's worth the effort to move toward it. Maybe it's just that the parentheses scare me...:) > -- > - > Jirka Kosek > e-mail: [EMAIL PROTECTED] > http://www.kosek.cz > -- Torben Wilson <[EMAIL PROTECTED]> http://www.thebuttlesschaps.com http://www.hybrid17.com http://www.inflatableeye.com +1.604.709.0506
Re: [PHP-DOC] See also
Hartmut Holzgraefe wrote: > it's things like automatic linking and adding () for > references in normal text, I thought that this I have hacked year ago. > rendering optional parameters a bit more > clever ... and ... and ... and ... I can devote some to do it, but is there anyone who wants to use XSL? When I asked same question year ago, almost noone respond. If there will be no usage of XSL, why to cutomize stylesheets? Jirka -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
Egon Schmid wrote: > I don´t have something against a rendering a "see also" block. But > rendering the content with a list would be a nightmare. We had a > discussion at which place should be comma in this list. This depends > on the language and I can guess it will be look very funny in > Arabic. localisation? ever heard of? easier to do in one place in the stylesheets than in every function reference during translation >> Ultimately, you guys (Egon, Goba, Harmut) should agree on correct >> markup pattern. I just offered my opinion from DocBook markup >> point of view. > > If Goba and Hartmut ignores me, so we will have never a agreement. getting a 100% consensus in a project like this is rather impossible, so everyone has to be prepared to be outvoted from time to time as long as you are not open to sensible arguments and just come up with "don't do so", "i told you not to do so", "it won't work" and (*) "it would be a nightmare" without backing this with arguments and without even having seen what it would be like you have dislosed yourself from the process of decision finding (*) no comma before the and in conformance with the University of Minnesota Style Manual >>>It is much better to write the "see also" notes >>>as before. Indeed it will be too complex if you consider the >>> > other > >>>languages with different rules for rendering. >>> > >>I see no problem here, if you are afraid of localizations of "see >> > also" > >>this is not problem as there is localization for this string >> > already > >>present in stylesheets. >> > > You can do so, but don´t make a list. please come up with *substantial* argument against a list type of environment the see-also sections in the function reference *are* lists, or lets say enumerations, of pages elsewhere in the manual right now the structure of this information is hidden in plain text with tags embedded into it makes no use but generation the exact text with links into it, but the information that it is a see-also list is hidden at the content level while it should be on the structure level as this would allow reuse of the see-also inter- dependencies easier localisation would be another point for the exactly same reason we use and friends for the prototypes instead of just copying the function prototype with arguments and return value from the source code and past it into the manual as is -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
Egon Schmid wrote: > Commit it and I hope Goba and Hartmut will not missuse it. please define "missuse" -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
Jirka Kosek wrote: > Gabor Hojtsy wrote: > > >>Two reasons, speed and customization level. Not all DSSSL customizations >>are ported to XSL customizations. This is in the TODO in BUILD SYSTEM >> > > If you tell my which, I can port them. well, have a look at the dsl subdir ;) it's things like automatic linking and adding () for references in normal text, rendering optional parameters a bit more clever ... and ... and ... and ... -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
Egon Schmid wrote: >>DocBook stylesheets contain code for inserting puncation between >> > list > >>items -- for example between authors in bibliography. This code is >>localized. Porting this code for our purposes shouldn't be hard. >> > > Oh, haven´t known that. come on, that's what the modular stylesheets and the localization stuff in there is all about in the first place (although it sometimes slightly fails, see "Copyright von ..." in german :( ) > Can it do the following in English: > > See also: func1 and func2. > See also: func1, func2, and func3. > > and for German or Hungarian: > > Siehe auch: func1 und func2. > Siehe auch: func1, func2 und func3. > > Look at the commas. Sure it can (with a little customisation on our side), and there would be no need to change the content on translations then. But once again: the comma before the 'and' is not mandatory, it depends on the style guide you refere to. Most languages seem to require the absence of a comma here while english has both options, so why don't we stick to a style compatible to all languages instead of sticking to a style rule that even the majority of the native english speakers i talked to don't like? -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
> We use since 1997 The Chicago Manual of Style and now EOD. Not sure why I brought it up actually. Philip
Re: [PHP-DOC] See also
Egon Schmid wrote: > Oh, haven´t known that. Can it do the following in English: > > See also: func1 and func2. > See also: func1, func2, and func3. > > and for German or Hungarian: > > Siehe auch: func1 und func2. > Siehe auch: func1, func2 und func3. > > Look at the commas. Yes, exactly. (I looked at commas, I know this problem.) Jirka -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
From: "Philip Olson" <[EMAIL PROTECTED]> > > See also: func1 and func2. > > See also: func1, func2, and func3. > > > > and for German or Hungarian: > > > > Siehe auch: func1 und func2. > > Siehe auch: func1, func2 und func3. > > Btw, it's okay english (perfectly acceptable) to not put a comma before > the and here, so: > > See also: func1, func2 and func3 > > Is fine. That is, iirc. We use since 1997 The Chicago Manual of Style and now EOD. -Egon
Re: [PHP-DOC] See also
> See also: func1 and func2. > See also: func1, func2, and func3. > > and for German or Hungarian: > > Siehe auch: func1 und func2. > Siehe auch: func1, func2 und func3. Btw, it's okay english (perfectly acceptable) to not put a comma before the and here, so: See also: func1, func2 and func3 Is fine. That is, iirc. Regards, Philip Olson
Re: [PHP-DOC] See also
Gabor Hojtsy wrote: > Two reasons, speed and customization level. Not all DSSSL customizations > are ported to XSL customizations. This is in the TODO in BUILD SYSTEM If you tell my which, I can port them. -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
From: "Jirka Kosek" <[EMAIL PROTECTED]> Egon Schmid wrote: > > I don´t have something against a rendering a "see also" block. But > > rendering the content with a list would be a nightmare. We had a > > discussion at which place should be comma in this list. This depends > > on the language and I can guess it will be look very funny in > > Arabic. > DocBook stylesheets contain code for inserting puncation between list > items -- for example between authors in bibliography. This code is > localized. Porting this code for our purposes shouldn't be hard. Oh, haven´t known that. Can it do the following in English: See also: func1 and func2. See also: func1, func2, and func3. and for German or Hungarian: Siehe auch: func1 und func2. Siehe auch: func1, func2 und func3. Look at the commas. -Egon
Re: [PHP-DOC] See also
Egon Schmid wrote: > I don´t have something against a rendering a "see also" block. But > rendering the content with a list would be a nightmare. We had a > discussion at which place should be comma in this list. This depends > on the language and I can guess it will be look very funny in > Arabic. DocBook stylesheets contain code for inserting puncation between list items -- for example between authors in bibliography. This code is localized. Porting this code for our purposes shouldn't be hard. Jirka -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
From: "Jirka Kosek" <[EMAIL PROTECTED]> > I finished modification of DSSSL stylesheets. They are 100% backward > compatible -- rendering is changed only on notes with role="seealso". If > you decide not to use it, you can always delete this rule in future. > Egon, can I commit it before I forget that I had this code on my > machine. Commit it and I hope Goba and Hartmut will not missuse it. -Egon
Re: [PHP-DOC] See also
> I don´t have something against a rendering a "see also" block. > But rendering the content with a list would be a nightmare. We had a > discussion at which place should be comma in this list. This depends > on the language and I can guess it will be look very funny in > Arabic. > > > I see no problem here, if you are afraid of localizations of "see > > also" this is not problem as there is localization for this string > > already present in stylesheets. > > You can do so, but don´t make a list. Adding do not mean we will use lists for rendering. But it opens the possibilty for many things, not just rendering. > If Goba and Hartmut ignores me, so we will have never a agreement. As this patch does not modify any current rendering, nor it sticks us to use lists for see also sections in the future, I think it is not an ignorance of your opinions, to say that we are at an agreement on adding this customization. Using lists or text will be another question. Just step over this one for now :) Goba
Re: [PHP-DOC] See also
From: "Jirka Kosek" <[EMAIL PROTECTED]> Egon Schmid wrote: > > Jirka, please don´t make changes for the rendering of the "see also" > > notes until there is a solution for the incomplete PDF manuals. IMHO > > it is an overkill. > You mean: overkill = too much markup? Yes. > In general you are right, but marking some block as "seealso" can be > very usefull when rendering and converting to other formars (e.g. HTML > Help). Handling role="seealso" on para will be possible but much more > harder then on note. Using note as a container allows you to use > simplelist if you want some longer list of functions or whatever else be > seealso-ed. I don´t have something against a rendering a "see also" block. But rendering the content with a list would be a nightmare. We had a discussion at which place should be comma in this list. This depends on the language and I can guess it will be look very funny in Arabic. > Ultimately, you guys (Egon, Goba, Harmut) should agree on correct markup > pattern. I just offered my opinion from DocBook markup point of view. If Goba and Hartmut ignores me, so we will have never a agreement. > > It is much better to write the "see also" notes > > as before. Indeed it will be too complex if you consider the other > > languages with different rules for rendering. > I see no problem here, if you are afraid of localizations of "see also" > this is not problem as there is localization for this string already > present in stylesheets. You can do so, but don´t make a list. -Egon
Re: [PHP-DOC] See also
> > HTML Help will definetly render the see also parts with different > > style. Now I have implemented some auto detection with some > > ugly text processing, searching for "see also:" commas and "and" > > words, and detected the see also parts this way for the HTML Help > > generation. This is not the right method though... > > Why your aren't using DocBook XSL stylesheet? They have direct support > for HTML Help and catching querying document tree is much more intuitive > than in DSSSL? Two reasons, speed and customization level. Not all DSSSL customizations are ported to XSL customizations. This is in the TODO in BUILD SYSTEM section. Speed comes from that we already have DSSSL generated files, and only need some transformations on them, and it seemd quicker to start from HTML and not back from XML. Now as the file size factor came in for the DSSSL generated HTML files, things are getting more complex, but this is not related to this talk... > > As seems the more versatile solution, with both > > enabling us to use paras and lists, +1 for this method. > > I finished modification of DSSSL stylesheets. They are 100% backward > compatible -- rendering is changed only on notes with role="seealso". If > you decide not to use it, you can always delete this rule in future. > Egon, can I commit it before I forget that I had this code on my > machine. +1 for adding it. Goba
Re: [PHP-DOC] See also
Egon Schmid wrote: > Jirka, please don´t make changes for the rendering of the "see also" > notes until there is a solution for the incomplete PDF manuals. how are these two topics related? have i missed something? > IMHO it is an overkill. > It is much better to write the "see also" notes as before. improving readability and structure is an overkill? the chance to extract the function relations is an overkill? > Indeed it will be too complex if you consider the other > languages with different rules for rendering. we are not yet at the list variant of role=seealso, just at wrapping up the paragraphs in a slightly different way and for the list approach i don't get the "too complex" argument as there we would just have to customize *one* place instead of seealso lists in thousands of functions -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
Gabor Hojtsy wrote: > > > In general you are right, but marking some block as "seealso" can be > > very usefull when rendering and converting to other formars (e.g. HTML > > Help). > > HTML Help will definetly render the see also parts with different > style. Now I have implemented some auto detection with some > ugly text processing, searching for "see also:" commas and "and" > words, and detected the see also parts this way for the HTML Help > generation. This is not the right method though... Why your aren't using DocBook XSL stylesheet? They have direct support for HTML Help and catching querying document tree is much more intuitive than in DSSSL? > As seems the more versatile solution, with both > enabling us to use paras and lists, +1 for this method. I finished modification of DSSSL stylesheets. They are 100% backward compatible -- rendering is changed only on notes with role="seealso". If you decide not to use it, you can always delete this rule in future. Egon, can I commit it before I forget that I had this code on my machine. Jirka -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
> In general you are right, but marking some block as "seealso" can be > very usefull when rendering and converting to other formars (e.g. HTML > Help). HTML Help will definetly render the see also parts with different style. Now I have implemented some auto detection with some ugly text processing, searching for "see also:" commas and "and" words, and detected the see also parts this way for the HTML Help generation. This is not the right method though... > Using note as a container allows you to use > simplelist if you want some longer list of functions or whatever else be > seealso-ed. > > Ultimately, you guys (Egon, Goba, Harmut) should agree on correct markup > pattern. I just offered my opinion from DocBook markup point of view. As seems the more versatile solution, with both enabling us to use paras and lists, +1 for this method. Goba [one [EMAIL PROTECTED]]
Re: [PHP-DOC] See also
Egon Schmid wrote: > Jirka, please don´t make changes for the rendering of the "see also" > notes until there is a solution for the incomplete PDF manuals. IMHO > it is an overkill. You mean: overkill = too much markup? In general you are right, but marking some block as "seealso" can be very usefull when rendering and converting to other formars (e.g. HTML Help). Handling role="seealso" on para will be possible but much more harder then on note. Using note as a container allows you to use simplelist if you want some longer list of functions or whatever else be seealso-ed. Ultimately, you guys (Egon, Goba, Harmut) should agree on correct markup pattern. I just offered my opinion from DocBook markup point of view. > It is much better to write the "see also" notes > as before. Indeed it will be too complex if you consider the other > languages with different rules for rendering. I see no problem here, if you are afraid of localizations of "see also" this is not problem as there is localization for this string already present in stylesheets. Jirka -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
> > As nobody else complained, > > didn't i? Yes, sorry :) Jirkas, idea solves the list problem, as I can see, while also allows us to use simple text if a list is not appropriate. What do you think abut this? Goba
Re: [PHP-DOC] See also
> > IMHO is on semantic level very close to seealso. Using role > > is standard DocBook way to make it different from standard note. > > Jirka, please don´t make changes for the rendering of the "see also" > notes until there is a solution for the incomplete PDF manuals. IMHO > it is an overkill. It is much better to write the "see also" notes > as before. Indeed it will be too complex if you consider the other > languages with different rules for rendering. It is great to hear some comments from you ;) First, adding this style sheet customization technically only adds an option for manual writers, to use this format, so it won't change the current PDF rendering in any way. Can you please explain, why do you think "it is much better to write the "see also" notes as before"? I would be glad to hear some opinions. Can you show us any language where not the ["See also" + list] form is used, with "See also" replaced by the translated version? We have example, table and other titles autogenerated this way for years now, and noone complained about them... Showing see also parts in a different notation makes them easily distinguisable from manual text. Our Windows manual user survey pointed out, that see also is one of the very best used parts of the manual, so as for useability, we should mark them clearly distinguisable from normal text IMHO. Goba
Re: [PHP-DOC] See also
Gabor Hojtsy wrote: > As nobody else complained, didn't i? -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
From: "Jirka Kosek" <[EMAIL PROTECTED]> > Gabor Hojtsy wrote: > > > > What is the exact syntax, will we still be defining commas and 'and' > > > within the blocks? > > > > Yes. It seems that using lists is much more complex for the rendering, > > as it involves adding commas and and words only where needed > > programatically. > > > > > > print, and > > echo > > > > You can't put mixed content directly into note in DocBook. You must wrap > it with para: > > > print, and > echo > > > > > > print > > echo > > > > This will require change in DocBook, you can use simplelist instead: > > > > print > echo > > > > > but the note form allows us to do things like this: > > > > > > print, and > > the notes on the CGI > > security page > > > > Once again, you must wrap it inside para: > > > > print, and > the notes on the CGI > security page > > > > > Either we choose "note" or "somelisttag", it is better > > than the current style. I have not seen too many > > comments about this on the list so far... > > IMHO is on semantic level very close to seealso. Using role is > standard DocBook way to make it different from standard note. Jirka, please don´t make changes for the rendering of the "see also" notes until there is a solution for the incomplete PDF manuals. IMHO it is an overkill. It is much better to write the "see also" notes as before. Indeed it will be too complex if you consider the other languages with different rules for rendering. -Egon
Re: [PHP-DOC] See also
> > > print > echo > > > > Once again, you must wrap it inside para: > > > > print, and > the notes on the CGI > security page > > > > IMHO is on semantic level very close to seealso. Using role is > standard DocBook way to make it different from standard note. IMHO we can go on with the "note role" version for now. One can use for a list with commas (no "and" word before the last one!). So this way, we can choose between an inline list or a typed in text, and I can only say I like the idea ;)) Please add the rendering :) Goba
Re: [PHP-DOC] See also
Gabor Hojtsy wrote: > > What is the exact syntax, will we still be defining commas and 'and' > > within the blocks? > > Yes. It seems that using lists is much more complex for the rendering, > as it involves adding commas and and words only where needed > programatically. > > > print, and > echo > You can't put mixed content directly into note in DocBook. You must wrap it with para: print, and echo > > print > echo > This will require change in DocBook, you can use simplelist instead: print echo > but the note form allows us to do things like this: > > > print, and > the notes on the CGI > security page > Once again, you must wrap it inside para: print, and the notes on the CGI security page > Either we choose "note" or "somelisttag", it is better > than the current style. I have not seen too many > comments about this on the list so far... IMHO is on semantic level very close to seealso. Using role is standard DocBook way to make it different from standard note. Jirka -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
> > > If I understand it correctly, see-also block is very simillar to > > > admonitions (note, warning, ...). So what about putting see-also inside > > > note > > > > > > > > > ... > > > > > > > > > Stylesheet can render it differently than note w/o role="seealso". > > > > As nobody else complained, I think we can go on with this style. > > Please make a DSSSL customization for this as you have the time, > > and then we can start experimenting with it, by adding see also > > parts this way. > > What is the exact syntax, will we still be defining commas and 'and' > within the blocks? Yes. It seems that using lists is much more complex for the rendering, as it involves adding commas and and words only where needed programatically. print, and echo does not look that nice, as print echo but the note form allows us to do things like this: print, and the notes on the CGI security page Either we choose "note" or "somelisttag", it is better than the current style. I have not seen too many comments about this on the list so far... Goba
Re: [PHP-DOC] See also
> > If I understand it correctly, see-also block is very simillar to > > admonitions (note, warning, ...). So what about putting see-also inside > > note > > > > > > ... > > > > > > Stylesheet can render it differently than note w/o role="seealso". > > As nobody else complained, I think we can go on with this style. > Please make a DSSSL customization for this as you have the time, > and then we can start experimenting with it, by adding see also > parts this way. What is the exact syntax, will we still be defining commas and 'and' within the blocks? Regards, Philip Olson
Re: [PHP-DOC] See also
> If I understand it correctly, see-also block is very simillar to > admonitions (note, warning, ...). So what about putting see-also inside > note > > > ... > > > Stylesheet can render it differently than note w/o role="seealso". As nobody else complained, I think we can go on with this style. Please make a DSSSL customization for this as you have the time, and then we can start experimenting with it, by adding see also parts this way. Thanks, Goba
Re: [PHP-DOC] See also
> > Well, that can also be fine, and better then para, > > because it is actually a list, and not a para, as > > it can be seen :)) The second one is better in > > "keys need to be typed" sense :) But, we have > > see also parts, where we have some functions and > > some parts refereced, and to express this, only > > the first one is appropriate. We also have see also > > parts without any functions, just part links... > > If I understand it correctly, see-also block is very simillar to > admonitions (note, warning, ...). So what about putting see-also inside > note > > > ... > > > Stylesheet can render it differently than note w/o role="seealso". I can both be happy with a list type or a block type see also element. The question, is whether we would like to automate it the way, as we need not put commas and "and" words between elements (list type), or simply write out the contents much like a note (block). To be abstract, far away from actual implementation: seeone seetwo seeother types seeone, seetwo, seeother, and types With both rendered with "See also:" prepended to the text and commas, and "and" words added between elements. The first one is clearer, with the second one, you have less to type. Using means using the second one. I can live with both. The second one is the easier to implement. As we choose one or the other, it will much likely will stay the same for a long time, as it is a big change in the docs... What the other people think here? Goba
Re: [PHP-DOC] See also
Gabor Hojtsy wrote: > Well, that can also be fine, and better then para, > because it is actually a list, and not a para, as > it can be seen :)) The second one is better in > "keys need to be typed" sense :) But, we have > see also parts, where we have some functions and > some parts refereced, and to express this, only > the first one is appropriate. We also have see also > parts without any functions, just part links... If I understand it correctly, see-also block is very simillar to admonitions (note, warning, ...). So what about putting see-also inside note ... Stylesheet can render it differently than note w/o role="seealso". Jirka -- - Jirka Kosek e-mail: [EMAIL PROTECTED] http://www.kosek.cz
Re: [PHP-DOC] See also
> what about > > >echo >print >printf > > > or > > >echo >print >printf > > > ? Well, that can also be fine, and better then para, because it is actually a list, and not a para, as it can be seen :)) The second one is better in "keys need to be typed" sense :) But, we have see also parts, where we have some functions and some parts refereced, and to express this, only the first one is appropriate. We also have see also parts without any functions, just part links... > > And let the DSSSL code to the rendering work, put > > > in comas and "and" words :) > > haven't played with role-dependant rendering yet, > > but i'm afraid this is an area where XSLT/XPath > have an advantage over DSSSL ... We already have special rendering for introduced by Jirka Kosek. This customization is in html-common.dsl. Goba
Re: [PHP-DOC] See also
Gabor Hojtsy wrote: >>>I would like to have a special rendering >>> >>+1 to something like this, will be cool to have 'See also' a bit more >>structured. >> > > I would like to see something like: > > > echo, print, > and printf > > > Or even: > > > echo > print > printf > what about echo print printf or echo print printf ? > And let the DSSSL code to the rendering work, put > in comas and "and" words :) haven't played with role-dependant rendering yet, but i'm afraid this is an area where XSLT/XPath have an advantage over DSSSL ... -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] See also
> > I would like to have a special rendering > > +1 to something like this, will be cool to have 'See also' a bit more > structured. I would like to see something like: echo, print, and printf Or even: echo print printf And let the DSSSL code to the rendering work, put in comas and "and" words :) The first is the easier to implement, one only need to copy the rendering code from eg. "note", and replace the note text with the see also text, and put it in a test, where only the paras with seealso roles are processed. The next is "somewhat" more complicated... Though my lack of DSSSL knowledge makes me be unable to do any of them :(( The see also rendering stuff would be extremely useful for the new CHM format, but can be also used to mark see also stuff special (eg. on palm machines :). Goba
