For the record, I suggested doing this in the original PhD proposal
document. But my proposal wasn't nearly as good as this one; well
done Edward! +2 from me on this.
-- Gwynne, Daughter of the Code
"This whole world is an asylum for the incurable."
On Mar 2, 2008, at 8:42 PM, Edward Z. Yang 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
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?
--
Edward Z. Yang GnuPG: 0x869C48DA
HTML Purifier <http://htmlpurifier.org> Anti-XSS Filter
[[ 3FA8 E9A9 7385 B691 A6FC B3CB A933 BE7D 869C 48DA ]]
