On May 21, 2010, at 1:12 PM, David Tajchreber wrote:
> On Fri, 21 May 2010 11:23:06 +0100, Richard Quadling wrote:
>
>> On 21 May 2010 11:15, Richard Quadling <rquadl...@googlemail.com> wrote:
>>> On 21 May 2010 10:08, Philip Olson <phi...@roshambo.org> wrote:
>>>>>
>>>>> The problem is not the tags per se. I can and have successfully
>>>>> compiled all the manuals I've altered (en, es, fa, fr, ja, tr) from
>>>>> the XML through to a Windows CHM (I'm on Windows after all).
>>>>>
>>>>> I'm not getting the warnings that you are seeing.
>>>>
>>>> For example, add <para>FOO</para> to strlen.xml outside of a refsect1
>>>> and you'll see the datetime xcinlude errors along with the real error.
>>>> It's confusing, and annoying, but I'm unsure how to solve said
>>>> annoyance.
>>>>
>>>> Regards,
>>>> Philip
>>>>
>>> configure.php already suppresses xinclude errors when the errors are
>>> being reported ( see print_xml_errors() ).
>>>
>>> It would seem that we also need to include the ability to suppress
>>> xpointer errors.
>>>
>>> But sometimes the errors may be needed, so I think the option
>>> --enable-xml-details should show the xinclude and the xpointer errors.
>>>
>>> Using ...
>>>
>>> if ($details || (!strpos($err->message, 'xi:include') &&
>>> !strpos($err->message, 'element include') && False ===
>>> strpos($err->message, 'XPointer evaluation failed:'))) {
>>>
>>> will now also suppress the XPointer errors, but show all the errors if
>>> the --enable-xml-details option is enabled.
>>>
>>> Enough do you think?
>>>
>>>
>> Nope. Seems that there are a LOT of errors which we suppress. Maybe
>> something to work on there.
>>
>> So, going to just suppress the XPointer evaluation errors along with the
>> other errors.
>
> The problem is definitely the xi:include tags. They reference sections
> that don't exist, notably destructorsynopsis for the datetime classes.
> Your patch to standardize the xi:include tags in the datetime files,
> r299458, introduced the bug. configure.php hides the warnings by default
> and that's why you're able to build all the manuals without seeing any of
> the warnings (the xi:fallback tag is a recovery for the missing resources
> but a warning is still generated). When a non-recoverable error occurs,
> configure.php iterates over all the warnings/errors, printing them out as
> it goes, which explains why the datetime xi:include warnings only show up
> when there is another error in the documentation tree. If you want to
> generate them, something as simple as what's below will do it.
>
> $doc = new DOMDocument();
> $doc->load('doc-base/manual.xml', LIBXML_NOENT);
> $doc->xinclude();
> var_dump($doc->validate());
The datetime documentation has essentially become (or is becoming) our model
for future (or ideal) documentation, at least when it comes to writing DocBook
XML for an extension that has both an OOP and Procedural API.
That said, the introduced xi:include tags sound a bit broken, so should be
fixed or reverted. I'm hopeful some DocBook geeks here will find the best
answer, but in the meantime it sounds like reverting this is the correct
solution.
Regards,
Philip
