On 9/13/07, Stanislav Malyshev <[EMAIL PROTECTED]> wrote: > > As long as all the xml:id are lowercased the actual filename doesn't > > really matter. > > Can you explain that - how tools know which filename to read? They can't > possibly try all imaginable capitalizations...
Let me try again; The function filenames are meaningless. Completely meaningless. The strpos() file could be named mYfIrStPHPdocContribution.IS-the-strpos-function.bat That filename is however is totally inconsistent with the filenames of the rest of the 40.000 files in phpdoc. Out of these 40.000 files there are 3.800 bad apples that use mIxEdCasEdFilEnaMes. All that matters (regarding filenames) is: when you "include" the file (via &reference.extension-dir-name.filename; is that the "extension-dir-name.filename" part is capsed correctly as our file-entities.php scripts generates all the system file entities based on the filename. Usually you will however not use these entities as they are automatically put into "functions.xml" for your convienients which you then "include" via &reference.extension-dir-name; into your reference.xml file. The xml:id is however very important. That is the actual *ID* of the file. That ID will is referred to when using <tag linkend="the-xml-id" />. There is noone in the world that wants to remember these 3000 files that have mixed case IDs so we are used to use all-lower-case-ids. Please don't add more IDs that we simply have to memorize. Also. The xml:id will be used as the generated filename. Meaning the xml:id="function.strpos" will generate the filename function.strpos.[php/html]. That ID cannot change. Ever. Never ever ever ever ever. (Did I mention that the xml:id cannot be changed?). Why not? Well. Because we really do care about our users. We don't want to break their links or fuck with their minds any more than we really have to. Changing the ID will break bunch of links to the manual and screw with some search engines. Not to mention all the linkend=s have to be changed too. Now. That being said. We have 3000 bad apples in phpdoc. Making those apples good is easy, but it will break bunch of links to the manual. We are thinking what we can do about those apples. > > Also, why xml:id should be lowercase? I have some ids that are ok in > mixed case, but all-lowercase they would look like incomprehensible > stream of letters. Will mixed case IDs break anything? I see they are > working OK. Or is it only for file-related ids? xml:id has nothing to do with the filename. Livedocs however cared alot about the filenames, but Docbook-xsl/dsssl and PhD don't give a damn about your filename. For our sanity, however, then we ask doc contributors to keep the filename[.xml] == xml:id. That way its just easier for us to look up. It has nothing to do with anything except our "coding standard" and how we (as humans) parse xml:id to filenames to look up. > > > There are couple of extensions that use mixedCasedFileNames, however, > > for consistency and love to the world, please use lowercased > > filenames. > > Is there any place I can look how to do it right? Last time I was > directed to http, but it looks like http is not the right place to look > either. You were pointed towards http for guadance in the markup. The http docs were closest to a "object oriented documentation skeleton" we had. Those docs do have alot of problems and have alot of "coding standard breaks". I actually don't even know if we really do have a official coding standard except for the skeletons.. http://doc.php.net/php/dochowto/chapter-skeletons.php If you do your homework however you'll quickly see what is the general way of doing things. Hope this reply made things clearer for you.. It really is not this big deal. Its just about consistency and how we read things, and most importantly; not breaking things for our readers. -Hannes
