Re: Re: A PHPDoc DTD: Making subfiles validate

On Mon, Mar 3, 2008 at 2:42 AM, Edward Z. Yang <edwardzyang@thewritingpot.com> 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