Ignore leading/trailing space in function/method/variable names when linking (closes #80)

[jimwins]

This doesn't quite work, I think the XML in my test case isn't right because the class name isn't actually get linked and I can see that it's not getting indexed correctly.

[haszi]

@jimwins The top level xml element needs a DocBook xml namespace declaration (ie. xmlns="http://docbook.org/ns/docbook") for PhD to pick up the role attribute correctly.

[haszi]

@Girgias We've talked about this when I wanted to fix this issue and IIRC you preferred fixing the markup in the doc repos instead of silently trimming them.

[alfsb]

If it is preferable to fix the sources instead silently trimming, then this code can be changed to verbosely generate alerts where some $target != trim( $target ); on rendering process, to make this type of linking fail easier to catch.

And/or re-implement these types of tests on doc-base scripts, as configure.php or QA tools does not generate alerts of this.

[alfsb]

Or to not trim silently, but trim and generate warnings.

[jimwins]

Adding the namespace declaration doesn't fix the test, it's still not indexing the name of the class for some reason. How that is supposed to get pulled from the contents is still dark magic to me.

Making this class of problem in the XML fail when building instead of just handling it is probably the better solution. Warnings will eventually just get ignored and start piling up.

[alfsb]

Making this class of problem in the XML fail when building instead of just handling it is probably the better solution. Warnings will eventually just get ignored and start piling up.

I think that adding warnings in PHD is still good, as linking fails may occurs for other reasons besides whitespace.

About warning/failing this in XML build/configure, I have a old code from when doc-base/scripts/translation was still a remote dream, that outputs this:

qaxml.w: en/reference/outcontrol/user-level-output-buffers.xml

  methodname handler

qaxml.w: en/reference/reflection/reflectionreference/fromarrayelement.xml

  classname ReflectionReference

[haszi]

Adding the namespace declaration doesn't fix the test, it's still not indexing the name of the class for some reason. How that is supposed to get pulled from the contents is still dark magic to me.

Try adding <titleabbrev>Example</titleabbrev> before the <classsynopsis> element. This might cause an issue with whitespace but should fix the indexing issue.

[jimwins]

Okay, found the problem with my test, and it's because the way the anchors are captured for <classname> in phpdotnet/phd/Package/PHP/XHTML.php based on the rules at line 151. (It uses the <titleabbrev>, not anything to do with the <classsynopsis> like I had expected.)

We could print warnings about missing links in the get*Link() methods in phpdotnet/phd/Format.php. That prints 6,687 warnings for doc-en right now. I haven't tried to do any sort of breakdown, but I think a substantial fraction of them are probably expected (like references to old functions in migration chapters, or un-namespaced classes within the documentation for extensions).

[haszi]

Making this class of problem in the XML fail when building instead of just handling it is probably the better solution. Warnings will eventually just get ignored and start piling up.

I think that adding warnings in PHD is still good, as linking fails may occurs for other reasons besides whitespace.

I agree with warning/failing in doc-base/configure.php but disagree with doing this in PhD as there are a lot of non-linking deprecated and removed constants and functions in the migration guides which would generate hundreds or more warnings on every run of PhD.

[Girgias]

@Girgias We've talked about this when I wanted to fix this issue and IIRC you preferred fixing the markup in the doc repos instead of silently trimming them.

I didn't have much preference but @salathe IIRC preferred fixing the XML sources.

I'm okay with allowing the linking, but it should warn so that the sources can be fixed.