Re: [PHP-DOC] New CHM manual opinions - please NOT!
From: "Marjolein Katsma" <[EMAIL PROTECTED]> > >> P.S. I personally wrote an extension for HomeSite: the PHP > >expression builder; this is based on PHP3; a version for PHP4 is > >planned. I'm also working on tools for even *better* integration of > >the PHP HTML help files with HomeSite. The current PHP Expression > >Builder can be found on my downloads page: > >http://hshelp.com/downloads.html > > > >Thomas showed me a version, which is uptodate with version 4.0.6. > > I've never heard of that - which is surprising given that I'm regularly on the HomeSite forums and even used to be Allaire's Product Manager. Can't seem to find it on his web site either - where could I find this? If it's done, I don't need to do it again, merely link to it, no? I'd be happy to - my todo list is already way too long... Ah I see. Call Thomas Weinert at [EMAIL PROTECTED] I hope he is now back in Köln and working. -Egon
Re: [PHP-DOC] New CHM manual opinions - please NOT!
From: "Marjolein Katsma" <[EMAIL PROTECTED]> > From http://weblabor.hu/php/newchm.php: > "Note, that this is not the official version, and there can be many errors and bugs to fix. The actual officical CHM manual can be found at http://www.php.net/download-docs.php. This does not mean, that this is a separate project. This will be the official version in the future, as it gets useable. " > > I'm quite alarmed at reading this. > I hope that you will continue to provide the HTML version of the manual! Having a CHM version only would be a loss. Sure, and Goba will do his best :) > Many PHP developers using Windows also use HomeSite - which has an extensible Help system for Help files in HTML format. The PHP help can be intergrated in the development environment, and is searchable in the context of all help files installed. A CHM format would make it incompatible and deny all HomeSite users this integration in their development environment: that would be a grave loss of functionality! I have seen yesterday a very cool and impressive function reference integrated in weaverslave. Thomas Weinert www.weaverslave.de. Thomas is the main author of weaverslave and we meet us on a regulary basis at our PHP meetings in Stuttgart, Germany. > Rather than CHM, give us a regular snapshot of the *commented* manual - the current downladable manual sorely misses the valuable comments. This is true :( > P.S. I personally wrote an extension for HomeSite: the PHP expression builder; this is based on PHP3; a version for PHP4 is planned. I'm also working on tools for even *better* integration of the PHP HTML help files with HomeSite. The current PHP Expression Builder can be found on my downloads page: http://hshelp.com/downloads.html Thomas showed me a version, which is uptodate with version 4.0.6. -Egon
Re: [PHP-DOC] New CHM manual opinions - please NOT!
At 22:12 2001-12-16 +0100, Egon Schmid wrote: >From: "Marjolein Katsma" <[EMAIL PROTECTED]> [snip] >> P.S. I personally wrote an extension for HomeSite: the PHP >expression builder; this is based on PHP3; a version for PHP4 is >planned. I'm also working on tools for even *better* integration of >the PHP HTML help files with HomeSite. The current PHP Expression >Builder can be found on my downloads page: >http://hshelp.com/downloads.html > >Thomas showed me a version, which is uptodate with version 4.0.6. I've never heard of that - which is surprising given that I'm regularly on the HomeSite forums and even used to be Allaire's Product Manager. Can't seem to find it on his web site either - where could I find this? If it's done, I don't need to do it again, merely link to it, no? I'd be happy to - my todo list is already way too long... Cheers, Marjolein Katsma HomeSite Help - http://hshelp.com/ - Extensions, Tips and Tools
Re: [PHP-DOC] New CHM manual opinions - please NOT!
Sander Roobol writes: > > From http://weblabor.hu/php/newchm.php: > > "Note, that this is not the official version, and there can be many errors > and bugs to fix. > > The actual officical CHM manual can be found at > http://www.php.net/download-docs.php. > > This does not mean, that this is a separate project. This will be the > official version in the future, as it gets useable. " > > > > I'm quite alarmed at reading this. > > I hope that you will continue to provide the HTML version of the manual! > > Having a CHM version only would be a loss. > > The new CHM-manual will never replace the plain HTML-manual! It only might > replace the current CHM manual. The HTML-manuals are way too valuable for > non-Windows users. > There's no need to worry about that. > > Sander Besides, remember that all manual formats are generated from the same XML source. Updating one format's appearance (CHM) has no impact on any of the others, since you don't change the source, just the the source-to-output convertor. -- Torben Wilson <[EMAIL PROTECTED]> http://www.thebuttlesschaps.com http://www.hybrid17.com http://www.inflatableeye.com +1.604.709.0506
Re: [PHP-DOC] New CHM manual opinions - please NOT!
> From http://weblabor.hu/php/newchm.php: > "Note, that this is not the official version, and there can be many errors and bugs to fix. > The actual officical CHM manual can be found at http://www.php.net/download-docs.php. > This does not mean, that this is a separate project. This will be the official version in the future, as it gets useable. " > > I'm quite alarmed at reading this. > I hope that you will continue to provide the HTML version of the manual! > Having a CHM version only would be a loss. The new CHM-manual will never replace the plain HTML-manual! It only might replace the current CHM manual. The HTML-manuals are way too valuable for non-Windows users. There's no need to worry about that. Sander
Re: [PHP-DOC] New CHM manual opinions
> I didn't like the new format, because: > - it is heavy. The pages take longer to open than they used to; > - cute graphics are cute, but useless. I don't need them to learn or > find the information I want; > - that purple background is horrible. It gives the whole viewing > area a darker aspect; it's hard on the eyes after a while; > - once again, you made a .chm file that is a real pain to view in > low resolution. This damn thing got me shoving the screen from side > to side all the time. I hope that, after your deaths, you and all Web > designers that insist on that kind of high-resolution-nazi attitude > go to a special room in Hell where you'll spend years being forced to > see everything you're ever allowed to see in very high resolution, > but wearing low res goggles nailed to your skulls that will never let > you see the whole area of whatever you're looking at, and one scroll > control button hanging from each of your buttock cheeks so that you > can move the goggle view and remember this thoughtful message every > time you try to sit down. As you may have read, we made a survey among our users. One question asked about their resultion, or more exactly the window size in which they use the manual. It turned out, that half of you would like to see a manual nicely viewable in a small window. The same results turned out for graphics intensive / pure text. This was quite predictable, anyway :) This is why we decided to make two versions, where anybody will be able to switch between a "graphics heavy" and a lo version anytime on their preferences page offline. > A useful idea: since you make the manual available in so many > different formats, here is another one you can offer: non-compiled > help package. A package containing all necessary files to build the > .CHM file with Microsoft Help Workshop, so that we can make our own > CSS and compile it. Bet no one suggested that yet. No, this was suggested before. It is in one of the comments posted along the results of our survey, and we received many personal emails asking for that. We decided to build a feature, so that a css code outside the CHM will also be usable for personal design preferences... This will allow anybody to make his own design for the manual. We do not plan to distribute an uncompiled version, though. Anybody can uncompile a CHM if he likes, with MS HTML Help WorkShop. Please consider, that this is a work in progress... Goba
Re: [PHP-DOC] New CHM manual opinions
Just downloaded the development CHM (Dec-4-2001). I haven’t used the first CHM, so I’m not sure if this is a carryover or what. Ummm, it’s really wide. Like, Main » Function Reference » Array Functions makes me scroll right to see the whole thing and I’m maximized at 1024 pixels. Kinduv annoying when you’ve got a gazzillion windows open and u just need to reference something. No, it is not a carryover, it is a problem with the design. It will go out with the new interface we will use. Thanks for your opinions, Goba
Re: [PHP-DOC] New CHM manual opinions
> I consider your idea to append comments under descriptions very useable, > but I don't think I would like your graphical format, please let us have > a chance to have an old design. It's more synoptic. We will :) Actually you'll have the chance to choose from a graphical or a non graphical format for viewing... Goba
Re: [PHP-DOC] New CHM manual opinions
> 1. See what I get when double click on it (startpage.png). We can see it without that screenshot. There is no opening page in the third sample, sorry. It was my fault, that this was not written on the page of the new chm manual. > 2. See my notes (notes.png). Please write your notes with words. This is a mailing list, many people received it. You have an old monitor, they have slow network connections... We appreciate your feedback, as written on the newchm.php page, the design will be completely replaced. You can see many design variants, some of them better than mine. > 3. There is no Usage for trim() function in all (there are 3 of them > as far as I remember) new chm versions. Thanks for this spot, I'll look at the "usage:" part generator code. There are more functions missing usage as reported... > 4. Where can I see the results of the survey? We are actually runing the survey, and currently do not know any results ourselfs... There is no processor script for the data right know, I am just working on it. I have only looked at the comments/wishes users added, and replyed to some of them... Goba
Re: [PHP-DOC] New CHM manual opinions
> If a function has more than one usage (e.g. > pg_connect) the title "Usage:" is displayed > in the vertical middle (valign="middle" in > HTML) instead of at the top (valign="top"). > > STATUS QUO > > int pg_connect ... > int pg_connect ... > Usage: int pg_connect ... > int pg_connect ... > > > MY SUGGESTION > > Usage: int pg_connect ... > int pg_connect ... > int pg_connect ... > int pg_connect ... Thanks for your idea. You are right :) This will probably be this way... Goba
Re: [PHP-DOC] New CHM manual opinions
> I like the idea that you have users notes at the buttom of every > command. I was wondering if there is a way to keep those notes upto > date since there are new users notes posted on www.php.net We will host the user notes in a separate CHM, so you can upgrade the user notes separately. We'll also implement some autonotification feature, so you can choose to check for a new CHM when starting up the CHM... Goba
Re: [PHP-DOC] New CHM manual opinions
> Currently it seems we will use this include technique for > displaying user comments in the same window, while it is > in another file: > http://www.dansteinman.com/dynduo/en/source.html > (see technique 2) With IE code only of course, no NS. > > > Will the doc be IE5+ compatible only ? I just made a sample user note includer from that DHTML stuff quted above by Dan Steinman. This is IE only, and works well if the file to include is not found. Then nothing will print out in the place of user comments... Try changing the src="chm_notes.html" to some "nonexsistent.html", and nothing will print. This is itself DHTML, but also we need to print out all tags in all files with JS, so the src will correctly point to the user notes file relevant to that page. This way if you are interested in user notes, you get this , and if you have the user notes HTML files downloadded (we will host it as a separate CHM), the src will point to the right HTML file inside the CHM. This URL is: mk:@MSITStore:C:\dir_where_you_put_your_chm\manual.chm::/file_inside.html This way we can include a user note from another CHM file, displaying it as a content of this HTML file. This is convinient, as you can choose whether you want to see user notes or not, and this seems to nicely degrade if the file is not found in the src="" attribute... Goba note_display.zip Description: Zip compressed data
Re: [PHP-DOC] New CHM manual opinions
> > Public discussion -> moved to the list. > > Also let Holget join in :)) Sorry Holger. Goba
Re: [PHP-DOC] New CHM manual opinions
> > So you need DHTML to make links ? I'm really interested too... > > But i think that's because i don't know how you generate the CHM doc. > > You can choose what mirror site to use for viewing the > page online. Using http://www.php.net/ always won't be > a Good Idea (TM), as it generates too much traffic for > the main site. Actually you wont be able to choose www.php.net > for online functions, only one mirror site... So what I wanted to say here, is that you need to print out links dynamically (eg. links to a mirror site with this page). This cannot be done without JS code. Goba
Re: [PHP-DOC] New CHM manual opinions
Putting this up on the list again :) Please use reply all to reply to our letters, so other people can join in the discussions :) > > OK, how can you do a "See this page online", > > "Report a bug on this page" functionality without > > DHTML? Please inform me, I am really interested... > > Sure! > > So you need DHTML to make links ? I'm really interested too... > But i think that's because i don't know how you generate the CHM doc. You can choose what mirror site to use for viewing the page online. Using http://www.php.net/ always won't be a Good Idea (TM), as it generates too much traffic for the main site. Actually you wont be able to choose www.php.net for online functions, only one mirror site... > Okay, i didn't know that you could dynamically Hide/Show users's comments. I > don't think that's very usefull but that's your choice. > When i read "DHTML" , i think "Layers dynamic positionning/resizing" but > it's not the case for the doc. No positioning, resizing or other thing is intended to be in here. > I don't really know how are made CHM files, i only make websites. So i don't > know how includes can be done with CHM. These are basically made up of HTML files. You can include one other HTML file in a HTML file as usual. Think of the contents of CHM files as usual offline HTML files ziped together with an added TOC and index. Currently it seems we will use this include technique for displaying user comments in the same window, while it is in another file: http://www.dansteinman.com/dynduo/en/source.html (see technique 2) With IE code only of course, no NS. > Will the doc be IE5+ compatible only ? > I just want to know how it'll work, i don't want to criticize...:-) As I know innerHTML works in IE4. I Hope so. We only need to be IE4+ compatible. I hope that's doable. Goba
Re: [PHP-DOC] New CHM manual opinions
> Public discussion -> moved to the list. Also let Holget join in :)) > > > Did you actually looked at the content? There has also > > > changed a lot. And it has already been discussed in the past > > > the the design is not optimal. > > > > No, but i thought we only were talking about design. > > Wrong assumption. Qouting the text from the newCHM page: | We ask you to try out the new format, and post your comments to | [EMAIL PROTECTED] with the subject "New CHM manual opinions". | A link to help you do so: mailto:[EMAIL PROTECTED]?subject=New | CHM manual opinions. Please write down your opinions about the design, | the new function page scheme, note, see also, warning and caution | boxes, etc. Any other tips, ideas, bug reports are appreciated. | Note that there are many more improvements, not just the design. | We would like to hear your opinions about the improvements and | the design as well. Isn't it clear that we are not talking about the design only :) > > Rethinking the design from the beginning is vital. If you want to keep the > > Gabor's one, please implement skins ! > > No one said that. I repeat myself, even Gabor himself said > its not perfect and he seeks forward for some designers. This > was a few weeks ago and a few people already contacted him > but it will take time (Gabor, I hope I'm right here ;) We are actually going to implement some sort of "skins" as you said. The plan is to let the user choose from three skins: - plain text, black and white - colored apperance - graphics intensive. A newbie probably will start from the third one, and as he is going to be more professional, he will change to the second or first... The interface will be the same on all the three versions, but the used graphics elements and color will differ. Again, we can only make this using DHTML, particularly CSS and some JS magic to print out the right CSS tag. Now as you can see we are asking people to complete a survey. Our new professional interface designer, Holger Eggert will use the information to design a unified interface, and the three skins up on them. At least this is what we plan, and I hope we can complete the task... > > The use of layers increases dev. time compared to pure HTML, and you'll > > always have things that won't work as they should, because even if your > > target is only IE, there are always bugs or changes from one version to > > another that introduce problems. > > You won't notice them immediately but there'll be. Always. > > Just have a look at http://webreference.com/dhtml/column26/width.html and > > see how Microsoft don't care about changing the way IE interprets > > HTML/DHTML. There are other pages in that article, look at the links at > > bottom. It shows differences between IE4 and IE5, but there are also > > differences between 5 and 5.5, between 5.5 and 6... The best thing is to use > > basic features, so you won't get serious problem. > > I know, i may seem to be paranoiac, but... Anyway, what improvements DHTML > > could bring to PHP's doc ? Choosing skins yourself for example :) It is also possible (although not planned) to get skin information from files outside the CHM, so you can program your own skin defining some JS functions, and put the files in the same directory that the CHM file is in, so being able to present the look and feel of the manual as you want. This is a nice idea, though IMHO we are not going to go on with it, as we would like to have a unified look and feel (even as we have three unified "look and feel"s). Yes, probably we will have problems with browser compatibilty. This was the main reson, why php.net dropped the popup boxes, and started to use much less DHTML. But here we know that our browsers are IE4+, and that helps much while designing the DHTML code. I used layers to show menus because it spares the less space from the screen. PHPDoc text should dominate above any navigational or design content sure. We are open to any suggestions, help, test results. Anything that can move this project forward. Goba
Re: [PHP-DOC] New CHM manual opinions
Public discussion -> moved to the list. On Sun, Nov 18, 2001 at 01:21:28PM +0100, Yann Lohier wrote : > > Did you actually looked at the content? There has also > > changed a lot. And it has already been discussed in the past > > the the design is not optimal. > > No, but i thought we only were talking about design. Wrong assumption. > > However, what Gabor did was a great work. Even if many don't > > like the new design (he even self says it could be better) he > > provided a great infrastructure for the new manual. > > Rethinking the design from the beginning is vital. If you want to keep the > Gabor's one, please implement skins ! No one said that. I repeat myself, even Gabor himself said its not perfect and he seeks forward for some designers. This was a few weeks ago and a few people already contacted him but it will take time (Gabor, I hope I'm right here ;) > The use of layers increases dev. time compared to pure HTML, and you'll > always have things that won't work as they should, because even if your > target is only IE, there are always bugs or changes from one version to > another that introduce problems. > You won't notice them immediately but there'll be. Always. > Just have a look at http://webreference.com/dhtml/column26/width.html and > see how Microsoft don't care about changing the way IE interprets > HTML/DHTML. There are other pages in that article, look at the links at > bottom. It shows differences between IE4 and IE5, but there are also > differences between 5 and 5.5, between 5.5 and 6... The best thing is to use > basic features, so you won't get serious problem. > I know, i may seem to be paranoiac, but... Anyway, what improvements DHTML > could bring to PHP's doc ? I don't get your problem. In this term, DHTML is only used on one platform for one 'browser software' which is HTML Help which in turn uses the IE rendering Engine. You can write JS code which runs on any of the browser you mentioned. As long as it helps users to navigate it should be done that way. Webreferences & Co are nice, but actually they don't apply. They deal with DHTML in server/browser environment. We do not have this particular environment here. I suggest, next time proper read think before writing such a mail. - Markus
Re: [PHP-DOC] New CHM manual opinions
On Sun, Nov 18, 2001 at 12:56:46PM +0100, Gabor Hojtsy wrote : > > > And please, don't use DHTML in the doc unless you REALLY know > > > what you do (i have 3 years of daily and very intensive DHTML > > > experience and i can assure that it's no use for a doc). This > > > is the worst thing to do !!! > > > > What is wrong with DHTML here? Elaborate. I don't see any valid point in saying not to us DHTML. It will only run withing the Help Browser so what? You even don't know it is there. - Markus
Re: [PHP-DOC] New CHM manual opinions
> > And please, don't use DHTML in the doc unless you REALLY know > > what you do (i have 3 years of daily and very intensive DHTML > > experience and i can assure that it's no use for a doc). This > > is the worst thing to do !!! > > What is wrong with DHTML here? Elaborate. OK, how can you do a "See this page online", "Report a bug on this page" functionality without DHTML? Please inform me, I am really interested... Sure! You cannot use any server side techniques. I myself like server side programming the best, but here if you would like to make dynamic content, the only way to go is DHTML. The other thing, dynamically including user notes, so people not interested in user notes do not need to download them, while others using them, just put the user_notes.chm file in the same directory, and the user notes appear just in the content of the page... This can only be done using some DHTML, particularly innerHTML tweaking of a div tag... So, if you don't like these done with DHTML, what do you advise us. Drop all the dynamic improvements, as the goal of the manual is to be static, or do it another way => than how? Goba
Re: [PHP-DOC] New CHM manual opinions
Did you actually looked at the content? There has also changed a lot. And it has already been discussed in the past the the design is not optimal. However, what Gabor did was a great work. Even if many don't like the new design (he even self says it could be better) he provided a great infrastructure for the new manual. On Sun, Nov 18, 2001 at 12:17:59PM +0100, Yann Lohier wrote : > And please, don't use DHTML in the doc unless you REALLY know > what you do (i have 3 years of daily and very intensive DHTML > experience and i can assure that it's no use for a doc). This > is the worst thing to do !!! What is wrong with DHTML here? Elaborate. - Markus
Re: [PHP-DOC] New CHM manual opinions
> Just a comment... the old CHM file scaled VERY nicely down to any screen > resolution (I use 800x600). > > The new CHM file is too wide, and I have to manually scroll to the right, > then scroll to the left again to see the beginning of the next line, then > back to the right again to see the end of that line gets annoying when > reading long sections, and really slows me down. This will definetely be corrected. I am sure. Goba
Re: [PHP-DOC] New CHM manual opinions
> You've probably already heard this but the link to download the new version > of the chm manual from Michigan is broken. It asks for a user name and > password. Oops... sorry :-) It's fixed now. Thanks for reporting. Sander
Re: [PHP-DOC] New CHM manual opinions
> > There are some works paralelly on the way. We welcome you with a draft if you > > would like to show what you think would be good... > > > Are you at the PHP-Conference in Frankfurt next week? I will present a > session on usability and interface design there. But it will be in > German. :-( Anyways, maybe we could talk about this thing a bit further. I'll be there, but German is not for me sorry :(( I tried to learn German after studied English for years, but it was a miscarried idea I can understand simple things in German, so I wont be lost in Frankfurt, I hope :). > If not, I will definitely make a design as a suggestion. But > it may take some time. When do you plan to finish the documentation? I hope we can officialy announce the new CHM the end of this year (Christmas present under the tree :). Many programming is needed to get the supporting functions (user preferences, online functions) working, and we need to collect many comments and make usability tests :)) We also need to separate the user notes to a standalone CHM, and figure out how we can glue them together with the manual, to form pages you see, while they are in the same manual... So there are many things to do, and I can't do it full time, so only expect a 'final' version by the end of this year... Goba
Re: [PHP-DOC] New CHM manual opinions
Hi! Am 30.10.2001 19:38 Uhr schrieb Hojtsy Gabor: > There are some works paralelly on the way. We welcome you with a draft if you > would like to show what you think would be good... > Are you at the PHP-Conference in Frankfurt next week? I will present a session on usability and interface design there. But it will be in German. :-( Anyways, maybe we could talk about this thing a bit further. If not, I will definitely make a design as a suggestion. But it may take some time. When do you plan to finish the documentation? Reagrds, Holger. -- T H E S C R E E N C O L L E C T I V E studio for interactive design munich * reykjavik
Re: [PHP-DOC] New CHM manual opinions
> > in a short time (although one of the goals of this new CHM is to show how > > many things can be using the current manual content as input). > > Just to note, with some transformations with XSLT, almost anything can use > the current manual as input. The majority of the transformation now done with PHP scripts to generate the CHM manual source HTML files, can be done with XSLT. It is done with PHP, because it is more widely used and known across team members, than any XSLT software :) So they can use it and contribute to it easily. Goba
Re: [PHP-DOC] New CHM manual opinions
On Thu, 1 Nov 2001, Hojtsy Gabor wrote: > in a short time (although one of the goals of this new CHM is to show how > many things can be using the current manual content as input). Just to note, with some transformations with XSLT, almost anything can use the current manual as input. And I'm learning that technology on a fast pace. Because I'm under a non-disclosure agreement, I can't tell exactly why, but it relates to some finnish banks, and they wouldn't like to the old currency (FIM) to show up in a new (EUR) systems' reports. And it's not only fixing the old system, they'll have a completely new system (that seems to have a strange sentence 'This product includes software developed by the Apache Software Foundation (http://www.apache.org/' when it either launches itself or the user selects 'Help->About'.) So, I think, I'm going to have a few ideas about the manual and how to produce some of the readable versions early in the next year. (If those hints were not enough, go to http://xml.apache.org/) -- Jouni
Re: [PHP-DOC] New CHM manual opinions
> Comments on the Help chm; > I think there are too many colours. The help manual is a daily > workhorse, with blue, orange brown etc it becomes a little too > busy and hard on the eyes. > > I also think it would be better to display the background image > less, say only on the main heading pages (rather than on every page, > even the function description detail pages). That background image will gone, as others reported that it is awful (and they were right :). > I like the faint light blue/grey background, better on the eyes > than white. This was the intention of it :) > I would like to see the "See also" section move to the top of the page > so that is added to the bullet items, so they become; > Purpose: > Usage: > Availability: > See also: > > I often find that it is when I read the first few lines of the description > and decide that this was not the function I wanted, that I need to immediately > see the "See also" items so I can go off to the function I really wanted. See also sections are sometimes placed in the text flow. Maybe we can implement some tags in the XML source to express this see also type you would like to see. There were some discussions about implementing such thing, so other formats can also benefit from the separation of see also blocks. To move up the see also list, we need to conceptually change the way we treat see also lists, so it is not likely we can do this in a short time (although one of the goals of this new CHM is to show how many things can be using the current manual content as input). > Previous, Next, Home and Up links are missing. I like these. Whenever I use > a function from a package that I have not used before I like to scan through > every function to familiarize myself with the package. The Next link > is great for this. I myself also missed these links. It was interesting, that noone reported these links as missing ones. I used next so often :)) But I can't think of any good place in the current design where it would be appropriate to put them... > PHP is a great language, the existing Help system is excellent. Your > efforts will make the Help system AWESOME! I hope we are on the right way to do this :) Goba
Re: [PHP-DOC] New CHM manual opinions
Thanks. We are aware of that issue, it is all about the manual notes, and the title of the pages being too wide. These two things need to be addressed. We have some ideas to do so... Thanks for you opinion, Goba - Original Message - From: Elizabeth Fulghum To: [EMAIL PROTECTED] Sent: Wednesday, October 31, 2001 8:44 PM Subject: [PHP-DOC] New CHM manual opinions Nice design on the new manual, I am one of those looking forward to the inclusion of the user comments. As I was trying it out, I noticed a couple of issues. While it looks great on screen, the layout is not very scalable. When I browse through the help files, I like to keep the contents/index/search/etc window open for easy navigation and searching. In the old manual, the content would "flex" depending on the width of the window - not so in this new version. See: http://home.dal.net/rabbitdog/screenshot.png I can see this as being one of the big "this annoys the heck out of me" issues with the new manual. Just my two cents, Liz Fulghum -- http://www.lipstickalley.com/ - Be Popular! Want to learn PHP? http://webdeveloper.earthweb.com/scripting/article/0,,12014_900521,00.html --
Re: [PHP-DOC] New CHM manual opinions
> I am a freelance web developer from India and would > like to submit a few samples.How do I do so?Can I mail > them to this email address or link it to my homepage. Please send it to [EMAIL PROTECTED] or put it up on your web site, and give the address of it. Thanks, Goba
Re: [PHP-DOC] New CHM manual opinions
> And one feature I would l really love to see is a link to the online > equivilant of the each help page to see what new coments have been > posted This is part of the online functions section right now :) > and drop down menus (they could just be combo boxes) to > related help documents. This was also planned, although it turned out, that there is no easy way to extract a related page list from the pages. There are see also sections, but they are not clearly separated (this build process tries to identify and mark them, but it is not 100%, as it won't recognize any see also notes in the text flow... So it seemed for now, the see also boxing is the only thing we can do... There is a movement to include some see also tags in the xml sources, but this is not used yet... Goba
Re: [PHP-DOC] New CHM manual opinions
On Tue, 30 Oct 2001, Hojtsy Gabor wrote: > > It should point to > > http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 > > Corrected in XML format of the manual. Do not expect it to > show up in CHM files for some days... make that atleast two weeks... crappy tech service here... regards, Derick - PHP: Scripting the Web - www.php.net - [EMAIL PROTECTED] SRM: Site Resource Manager - www.vl-srm.net -
Re: [PHP-DOC] New CHM manual opinions
> IMHO distributing the notes is the wrong way to go > as it gets even less likely this way > that a manual maintainer goes over the notes and > tries to update the page itself > > *unless maybe* if we could get some sort of contributed > notes rating system so that maintainers get a quick clue > about which notes are worth to look at for manual improvements ... > > ... hmmm ... > > ... looks like i have found myself another subtopic for > my conference talk next week ... See http://gtk.php.net/manual/en/ The rating system is made by Colin as I can remember. He offered a porting if it seems to be good in the gtk manual. It is unlikely that note maintainers can get on with the speed, so there will allways be valuable notes. We would like to ease the work of our users IMHO, and most of the want to have the user notes offline. At least as I see... Goba
Re: [PHP-DOC] New CHM manual opinions
> > Please set .chm mime type as bin. Is it impossible to download useable > > chm documentation now. > > Yes, that should be done, although some browsers (like Lynx and Opera) > handle it fine the way it is now. On what server? weblabor.hu? Other testers seemed to download it correctly. What browser you use? Goba
Re: [PHP-DOC] New CHM manual opinions
> It should point to > http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 Corrected in XML format of the manual. Do not expect it to show up in CHM files for some days... Goba
Re: [PHP-DOC] New CHM manual opinions
Hojtsy Gabor wrote: > Including user notes in the manual is a greatly requested feature. But > as you can see on the download page, we plan to make it two (tha manual > and the notes). So you don't need to download the notes if you don't want > to. IMHO distributing the notes is the wrong way to go as it gets even less likely this way that a manual maintainer goes over the notes and tries to update the page itself *unless maybe* if we could get some sort of contributed notes rating system so that maintainers get a quick clue about which notes are worth to look at for manual improvements ... ... hmmm ... ... looks like i have found myself another subtopic for my conference talk next week ... -- Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
Re: [PHP-DOC] New CHM manual opinions
> I saw the page about the new help file. You said you could need a new > design. Is this still the case? If so, maybe I could help you out. There are some works paralelly on the way. We welcome you with a draft if you would like to show what you think would be good... Goba
Re: [PHP-DOC] New CHM manual opinions
> The tables and boxes contained in the righthand > content window (user contributed notes, notes, > warnings, see also) are too large to read on a > 1024x768 res monitor without maximising the CHM. > > This is a problem for people like me, stuck developing > on a laptop with a 1024x768 monitor (cruel and unusual > punishment!). > > By the time I can read all the content in these boxes, > the CHM must be 1024 pixels wide, which is bad because > I also need to see my html editor, phpmyadmin and > several browser windows All these problems are because the manual notes. We will wrap them or put in a completely separate table, so they'll fit in much smaller windows. > For instance, the lefthand margin, while attractive, > takes up valuable screen real estate. Why not put it > on the righthand side for people with better monitors > to enjoy? OK, I have gone too much designing. There are many things to consider... The design will be replaced with a better one... > Another idea is to make the fonts a point or two > smaller, since they are quite generously large. (At > least this is unlike some places where the code is > displayed in 6pt Eyestrain Monospace...) But these > fonts would still be very readable at a point or two > smaller. IMHO, it is not a good point to make fonts smaller... Goba
Re: [PHP-DOC] New CHM manual opinions
> Ref: New CHM format of the PHP Manual at: > http://weblabor.hu/php/newchm.html > > >Note, that this is not the official version, and there can be many > >errors and bugs to fix. The actual officical CHM manual can be found > >at http://www.php.net/download-docs.php > > Is this to say that you're putting together a help manual as a > separate effort from the 'official' version? If so, why not avoid > all the confusion that's going to create and just contribute your > efforts to the real deal? I thought PHP was open source? This is a manual to be the official. Currently it is under construction. I uploaded and managed this on a separate sever, because I have much more control on this server than the php.net one. Using the php documentation group email address for feedback indicates that this is a thing within the group. Anyway I was one of the coders behind the current build scripts of the CHM manuals (not the only one). Goba
Re: [PHP-DOC] New CHM manual opinions
> Wonderful! This is exactly what I've been longing for on those occasions > when www.php.net/my_question is inaccesible. Hope we can get as much of the online content as we can, so people can access things more quickly... > I've been browsing the helpfile for a few minutes and what I've noticed > is that the width of the manpage changes a lot. For example the "ClibPDF > functions" and "HTTP functions" pages are wider than most other pages. > The both give me a horizontal scrollbar. > > I assume that this is due to some -tags in the html and not a > result of your coding. This is because the user notes. It will be corrected. > I really like the layout of the pages. However I could not have > deciphered the icons in the head without the mouseover texts. Note that the design will change much accoring to other users reponses... Goba
Re: [PHP-DOC] New CHM manual opinions
> hi, i downloaded the .chm manual from: > > http://www.php.net/download-docs.php > > i downloaded the .zip version and after unpacking file size is: This was not the actual CHM file we would like you to test. :) The test file can be found here: http://weblabor.hu/php/newchm.html Quite an unofficial place ;) For your download probelms, if you use netscape please right click on the file and open save as from there. Goba
Re: [PHP-DOC] New CHM manual opinions
Thanks for your feedback. Manual notes can be incldued in any format, maybe Palm would not be too realistic, as the notes themselfs take as much disk space as the manual itself... But other formats may follow in the user notes inclusion :) I don't know when a final version will be out, not before next week's end... Please be patient, it will be on the homepage of php.net :) Goba - Original Message - From: hamus@work To: [EMAIL PROTECTED] Sent: Tuesday, October 30, 2001 9:55 AM Subject: [PHP-DOC] New CHM manual opinions Dear Author, Hello! I'm Hamus Lee who is a PHP user in Hong Kong. Your New CHM Manual is really great, All my friends and me also feel glad for the new feature especially the "User Comment" included in the new version. Will it have more version such as MAC or PALM version? Also, it seems that the Sample Version is not likely the final version right? Would you please tell me the realease date of the final version? We are all looking forward on that :) . Keep On with the wonderful work! Regards, Hamus Lee
Re: [PHP-DOC] New CHM manual opinions
> It is GREAT. Thank you very much. I develop PHP on a win2k box and the CHM > file makes browsing the documentation as easy as 1-2-3. Thank you very much. > One thing: I noticed that you get a horizontal scrollbar even when the > window is fairly wide. I attached a screenshot of what I mean. This may be because the user notes. If a user note contains unbreakable text (text without any spaces) it just spans as much width as it can... Goba
Re: [PHP-DOC] New CHM manual opinions
> As far as I know, previous (official) PHP documentation in .CHM format was > compiled without indexes. So, it was not possible to use it for context > sensitive help systems.. I hope now it will :-) The actual ones you can download from http://wwwphp.net/download-docs.php are with indexes. The really old versions were without indexes, but they are in the docs for quite some time now. Goba
Re: [PHP-DOC] New CHM manual opinions
> I've found a little error in the str_replace function description, in > the user contributed notes section, specifically under > the "[EMAIL PROTECTED]" contribute. The syntax of the code is not correct. Please report errors in notes at [EMAIL PROTECTED] Thanks. This info will be in the about notes section :) > Aside of this, I think it would be useful to add the possibility to > collapse the user contributed notes section and simplify the view. What would be available in this collapsed view? Goba
Re: [PHP-DOC] New CHM manual opinions
> I have tried the new PHP chm manual for 1 day. I like the new content a > lot better, but I agree that the design could be improved. > > Here's my feedback: > > 1. The background bitmap looks tacky (enlarged, jagged, etc.). I don't want to > download unneeded images either. Just HTML please. The total size of __all__ images now included in this CHM manual is 20k 20 kilobytes. Yes. Is it that much in size? OK, the design is not too good... Some contributors are on the way to make it clear and more useable... > 2. The comments are in red/orange. This makes the comments the most visible > portion of help, instead of the actual online manual. You are right. This is not correct... > Also the comments are uneven in quality, some good, some out-of-date, > some have bugs in the sample source code. Including user notes in the manual is a greatly requested feature. But as you can see on the download page, we plan to make it two (tha manual and the notes). So you don't need to download the notes if you don't want to. > 3. The HTML on a 1024x768 screen, it doesn't fit too well, and I have to scroll > horizontaly to read the manual. Perhaps break up a manual page into 2 html tables. > Upper table is contains the main manual, the lower table which is stretchable contains > the comments. Good suggestion :) I'll see what I can do about it... We need a table whose width is just as much as the window width and a table bellow that, whose size corresponds to the notes size... Goba
Re: [PHP-DOC] New CHM manual opinions
> I hate to seem like an amateur, but after downloading the file I cannot > get it to open. I keep getting the following message: > > hh.exe has generated the following errors and will be closed by > Windows. You will need to restart the program. > > Any ideas on how to fix the problem or instructions of some sort that > may help me get through this. Do you used netscape to download the files? If so, please download it as clicking on it, and choosing Save As... Hope it helps... Goba
Re: [PHP-DOC] New CHM manual opinions
> Please set .chm mime type as bin. Is it impossible to download useable > chm documentation now. Yes, that should be done, although some browsers (like Lynx and Opera) handle it fine the way it is now. Sander
Re: [PHP-DOC] New CHM manual opinions
> sorry bout that, since i DL the pdf version at the same time > got a little mixed up. > t. OK. But about the CHM file, you say that the file is 1,856,192 bytes large. Is that still correct? If so, you should try downloading the file again because it should be larger than this. It should be 2.376.158 bytes. Sander
Re: [PHP-DOC] New CHM manual opinions
> hi, i downloaded the .chm manual from: > http://www.php.net/download-docs.php > i downloaded the .zip version and after unpacking file size is: > 1,856,192 bytes How can you download a .zip version of the .chm manual? There is none. (it would be useless anyway, because .chm is already pretty strong compressed). Sander
Re: [PHP-DOC] New CHM manual opinions
the strange thing: other help files (default/and not default) work fine, this prob. occurs only with this specific .chm maybe i should have mentioned that... and no, i havent installed any external, 3rd party, odd andor strange versions of htmhelp. but i can try to copy from a freshly installed w2k machine its hh.exe, is there any other lib or bin which i might have to replace? tnx, t. At 15:31 30.10.01 +0100, Markus Fischer wrote: >Short answer: your HtmlHelp installation is broken. > >Long answer: There is none. Try to fix it by updating it (but, >afaik, there aren't any updates for w2k about HH) or get some >trusted bianries from friends. > >However, I wonder what could have done this. Tried to install a >separate HtmHelp version (which W2K doesn't need)? > >- Markus > >On Tue, Oct 30, 2001 at 03:21:47PM +0200, Tomasz Abramowicz wrote : >> hi, i downloaded the .chm manual from: >> >> http://www.php.net/download-docs.php >> >> i downloaded the .zip version and after unpacking file size is: >> >> 1,856,192 bytes >> >> im not sure what info you need to debug, >> heres some general stuff from the windows properties window: >> >> i am using: >> >> Microsoft Windows 2000 >> 5.00.2195 >> Service Pack 2 >> >> on a Computer: >> x86 Family 6 Model 7 Stepping >> 3 >> AT/AT COMPATIBLE >> 261,680 RAM >> >> the problem: >> >> when i double click the file windows says: >> >> >> hh.exe has generated errors and will be closed by Windows. You >> will need to restart the program. >> >> An error log is being created. >> >> OK. >> >> >> if i drag&drop the icon onto an opened help, it asks me if i want to >> open it or save etc.. ...if i press open the error described above occurs again. >> >> just thought i'd let you know.. >> t. > >-- >Markus Fischer, http://guru.josefine.at/~mfischer/ >EMail: [EMAIL PROTECTED] >PGP Public Key: http://guru.josefine.at/~mfischer/C2272BD0.asc >PGP Fingerprint: D3B0 DD4F E12B F911 3CE1 C2B5 D674 B445 C227 2BD0 > -All your scripts are belong to Zend-
Re: [PHP-DOC] New CHM manual opinions
Short answer: your HtmlHelp installation is broken. Long answer: There is none. Try to fix it by updating it (but, afaik, there aren't any updates for w2k about HH) or get some trusted bianries from friends. However, I wonder what could have done this. Tried to install a separate HtmHelp version (which W2K doesn't need)? - Markus On Tue, Oct 30, 2001 at 03:21:47PM +0200, Tomasz Abramowicz wrote : > hi, i downloaded the .chm manual from: > > http://www.php.net/download-docs.php > > i downloaded the .zip version and after unpacking file size is: > > 1,856,192 bytes > > im not sure what info you need to debug, > heres some general stuff from the windows properties window: > > i am using: > > Microsoft Windows 2000 > 5.00.2195 > Service Pack 2 > > on a Computer: > x86 Family 6 Model 7 Stepping > 3 > AT/AT COMPATIBLE > 261,680 RAM > > the problem: > > when i double click the file windows says: > > > hh.exe has generated errors and will be closed by Windows. You > will need to restart the program. > > An error log is being created. > > OK. > > > if i drag&drop the icon onto an opened help, it asks me if i want to > open it or save etc.. ...if i press open the error described above occurs again. > > just thought i'd let you know.. > t. -- Markus Fischer, http://guru.josefine.at/~mfischer/ EMail: [EMAIL PROTECTED] PGP Public Key: http://guru.josefine.at/~mfischer/C2272BD0.asc PGP Fingerprint: D3B0 DD4F E12B F911 3CE1 C2B5 D674 B445 C227 2BD0 -All your scripts are belong to Zend-
Re: [PHP-DOC] New CHM manual opinions
It should point to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 Sander - Original Message - From: POLIN spa To: [EMAIL PROTECTED] Sent: Tuesday, October 30, 2001 10:30 AM Subject: [PHP-DOC] New CHM manual opinions Dear PHP staff, first of all compliments for the developement of the PHP manual into chm format. I downloaded it and I'm using it strongly. I would like to advice you about a broken link that I found inside the manual. Please goto -->> -- Function Reference HTTP functions -- header After few lines you will find this: Note: HTTP 1.1 requires an absolute URI as argument to Location: includingetc etc Location points to a broken link, could you check this? Hope helps, Kindest Regards Ciao Andrea (Italy).
Re: [PHP-DOC] New CHM manual opinions
Hello Bruno, Monday, October 29, 2001, 8:01:27 PM, you wrote: BF> I've taken a good look at the new PHP manual design. I am a webdeveloper BF> (and sometimes designer), and i've looked already through a "couple" of BF> pages :) BF> I have to say that it looks a bit like the manual is straying from its BF> initial purpose. Not that it actually IS, really, it is a manual after all. BF> But the new proposed enhancements seem, as far as I (and the person sitting BF> next to me who does a great deal of design) am concerned, the new proposed BF> design hinders readability quite a lot. A manual ought to be precise and Aha! Just like a said! :)) BF> well-written, and while eye-candy is certainly attractive and can help in BF> leading the eye and not allowing for the reader to get too tired for BF> looking at the "same old text". The Konqueror help-system does look good, BF> but mainly because there are softer contrasts and the use of cool (cold?) BF> colors, blue in this case, helps a lot. Yess! :) BF> The new proposal doesn't help a lot for readability. Things ought to be BF> kept simpler, especially, with simples colours and not so many contrasts in Yeah! :) BF> the text area. If I can manage to find some time, I'll try for a design of BF> my own, though I can't promise. BF> Bruno Ferreira -- Best regards, Olexandrmailto:[EMAIL PROTECTED]
Re: [PHP-DOC] New CHM manual opinions
Andrey Ivannikov <[EMAIL PROTECTED]> irta: > What text you would like to send about the manual? We have not recevied any text in your letter... Goba
Re: [PHP-DOC] New CHM manual opinions
On Sun, Oct 28, 2001 at 11:36:26PM +0100, Hojtsy Gabor wrote : > http://weblabor.hu/php/newchm.html > > Now path menu is also included on all pages! Great :-) As you said, colorful as it was before. The icons are really very 'non-expressive'; names would be much better. Also, the overlapping background is very annoying to me. Although the image has been brighten it disturbs the reading flow because the most informative section of any function is exactly at the top. Path menu is really a great thing now. - Markus
Re: [PHP-DOC] New CHM manual opinions
> On Sun, Oct 28, 2001 at 11:21:29PM +0100, Hojtsy Gabor wrote : > > Why would be the text menus better? > > You don't have to learn (which way ever) what they mean. At > current the don't tell much if you don't take a very close look. People grown up on Windows programs, eg using PHPed, HomeSite, Dreamweaver or any major authoring tool are using toolbars. Toolbar icons are just the same, man need to be familiar with them... OK, I understand what you would like to say, see what others think I have just uploaded a newly designed manual. It is even more colorful. If you would like to spare some more bandwith on it, you can download the new one, or just see the new screenshot: http://weblabor.hu/php/newchm.html Now path menu is also included on all pages! Goba
Re: [PHP-DOC] New CHM manual opinions
On Sun, Oct 28, 2001 at 11:21:29PM +0100, Hojtsy Gabor wrote : > Erm. This was not intended in any of the CHM plans. The > environment is so different, there is not too much layout > we can get from the site... I was talking about colors. It's also a bit spare and thats good IMHO. Sorry for second reply to same mail. - Markus
Re: [PHP-DOC] New CHM manual opinions
On Sun, Oct 28, 2001 at 11:21:29PM +0100, Hojtsy Gabor wrote : > Why would be the text menus better? You don't have to learn (which way ever) what they mean. At current the don't tell much if you don't take a very close look. - Markus
Re: [PHP-DOC] New CHM manual opinions
> While you mention it, I also found it a bit too colorful. The > idea of putting the user comments is the biggest plus. But I'ld > like to see the same colors/layout as before. I had no plan of providing two separarate formats (it would be pointless to generate them). Only one format will stay. Maybe the "old" one, if it is what most people would like to see. > Maybe as much as possible tied to the website. Erm. This was not intended in any of the CHM plans. The environment is so different, there is not too much layout we can get from the site... > And the icons on the top should really be text IMHO. The idea behind small graphics icons is: - the graphics should not be too much (IMHO it is not too much now :) - people not used to that menu can see the function of any icon by moving the mouse over it (image map with alt="") - people used to that menu would not like to see long text menus across the whole screen Why would be the text menus better? Goba
Re: [PHP-DOC] New CHM manual opinions
> I'm not a professional designer and I'm not a designer at all (maybe > yet). But I don't like this new design. "Old" chm is better for me > because it looks really good. It's not so colorful but it's very > convenient, comfortable to use because there are no needless pictures > and icons, just plain hypertext. Currently the icons are not so useful, but they'll have useful meaning when this type of manual will be ready (ie. instant bug reporting, and updating to newer versions). > Just compare "good old" chm (old.jpg) > with the "new" one (new.jpg). Do you feel the difference? You know, > it's like, for example, music. I mean you can add background music for > this document but what for? The music will just irritate you. Here is > the same situation. Maybe I'm too conservative but I think when you > simply add User Contributed Notes to "old" chm and leave it as it is, > it will be the best variant. The "new" chm is better for now (because > of user notes) Is it just the user notes, you see as added value? Do you think, that clearly separated notes, warnings, see also sections, separation of function properies makes the manual easier to read? Are these all best in the "old" CHM format? > but I hope you'll find a good designer. I hope so :) I am just uploading a newer version. It is much more colorful. You won't like it I am sure. I went ahead with colors and there is no white anywhere anymore... But I am too not a good designer. Many readers said that this new design is cool, but I don't like it too (although I made it). Goba
Re: [PHP-DOC] New CHM manual opinions
While you mention it, I also found it a bit too colorful. The idea of putting the user comments is the biggest plus. But I'ld like to see the same colors/layout as before. Maybe as much as possible tied to the website. And the icons on the top should really be text IMHO. Ok, apart from that ab big *hug* from to the new manual (creator ;). - Markus
Re: [PHP-DOC] New CHM manual opinions
Anyone who whould not like to hear anything from the new CHM manual can now filter this subject line. Anyone who would like to participate in discussions, can read and answer such letters. This was just some tecnical information :) Goba
