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.

[alfsb]

Rephrasing what I said above, when get*Link() detects that a trimmed argument succeeds while a raw argument fails, a warning should be issued, so the sources should be fixed.

[alfsb]

Sorry, closed by accident.

[alfsb]

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).

I cannot talk about PhD warnings, as I almost never run this code, but my incursions on doc-base, creating and enabling warnings there, was mostly positive. And as I said here, enabling warnings only when the generated link succeeds after the input is trimmed, would generate valid warnings.

That is, first tries to create the link, on failure trim() the input, if it now succeeds, there is some XML source needing a fix.

--

And thinking of the whole process now, maybe re-enabling the mailing of automatic building of manuals on mail lists, including the PhD generation, would make these warnings more visible, and less prone to accumulation.

If not re-enabling the automatic emails on every build, at least weekly, or for only a select few translations, where the translation process got severely impacted by the interruption of these mails.