On 03/03/2008, Hannes Magnusson <[EMAIL PROTECTED]> wrote: > On Mon, Mar 3, 2008 at 2:42 AM, Edward Z. Yang > <[EMAIL PROTECTED]> wrote: > > Ok, so here's the new plan: > > > > 1. Create a PHPDoc DTD (with its own public ID) that contains any magic > > trickery we want to maintain. Even if it ends up being identical to > > DocBook's DTD, specifying our own gives us flexibility. Setup the > > necessary catalogs to use this DTD. > > > > 2. Determine what the format of XIncludes for subfiles should be. It > > should be possible to get rid of file-entities.ent, and the > > entities.*.xml files should become XInclude-able (currently not, since > > they don't have a single parent node) XML files that contain XIncludes > > (currently have entities). > > > > 3. Create two scripts to perform the conversion: one will add the proper > > DocBook declaration to all the documents (and possibly change the > > default xmlns attribute; remember <!DOCTYPE $root PUBLIC ...), the other > > > No no no. Changing the namespace defeats the whole purpose of this change. > Adding xml:lang attribute is however something I've been wanting to do > for a while. > > > > > will convert applicable entities to XIncludes (determining which ones to > > convert may be a challenge; for certain &reference.*.entities.functions; > > and &reference.*.*; as well as the entries in manual.xml.in). > > > > 4. Test > > > > 5. Commit > > > > To keep things manageable, testing should be done on a single folder > > (say, en/security) before rolling things out to everybody (these means > > the XInclude method and the entity method must be able to coexist). > > Also, we want to automate as much as possible, to make sure translators > > don't get saddled with this huge format shift. > > > > Anything I missed? > > > Yes. Magically include of english documents for > non-existing-translated-document. > > > > <xi:include href="/phpdoc/lang/foo.xml"> > <xi:fallback> > <xi:include href="/phpdoc/en/foo.xml" /> > </xi:fallback> > </xi:include> > > Where /phpdoc/lang/ points to the current language (mapped via > catalog) and /phpdoc/en/ enforcing en as fallback. > Easysmeasy... this is however 5lines for what (today) we have 1line... > > Not really userfriendly solution, any ideas? > > > -Hannes >
Considering that we are producing high quality technical documentation, surely it is fair to assume that it would be understood that there would be SOME hoops to jump through? And that sometimes there will be some changes to the hoops. Otherwise we would have finished and we wouldn't be discussing this. So, if 5 lines are needed so that our dox require NO magic at all (i.e. some third party docbook reader just read it and had NO problems), then surely this is better than insisting on having to pre-process this, configure that, etc. (I may not know what I'm talking about here - I'll leave that up to you to decided!). -- ----- Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 "Standing on the shoulders of some very clever giants!"
