Broken link errors #105
Comments
|
|
Looking more closely at this, these are actually not Quickbook warnings. (We do have issue #76 regarding some Quickbook warnings.) The above errors are emitted by the DocBook stylesheets signifying broken links. I believe we're generating some invalid links like this:
I believe the comma in the ID is causing the problem. (The DocBook stylesheets apparently don't like this.) Adding this to common.xsl fixed the few examples I reproduced. I'll have to check to see if there are other characters causing the problem (e.g. ampersands): <replace pattern="," with="_comma_"/> |
|
@alandefreitas I'm still working on identifying other causes of the broken links in the other projects using docca, but I'm having trouble reproducing with the utility library, because I'm getting a different error: Are you getting this error too, or is it just me? |
|
This is what I get: (dozens of similar warnings...) What's funny is I don't even see your first line after the configuration checks: I have been using the docca develop branch. The script to replicate the issue should also include for completeness but that shouldn't be a problem. |
|
I'm still trying to reproduce the errors but am running into a different error. I see a couple files in boost/bin.v2/libs/utility/doc/_reference-dir that look like the offending ones: 'structboost_1_1call__traits_3_01_t_01[_n]_4.xml' Do you see these files in that same directory? |
|
For now, I was able to work around the problem on my end by temporarily commenting out some of the library code: diff --git a/include/boost/detail/call_traits.hpp b/include/boost/detail/call_traits.hpp
index feca93d..981fbe8 100644
--- a/include/boost/detail/call_traits.hpp
+++ b/include/boost/detail/call_traits.hpp
@@ -140,6 +140,7 @@ struct call_traits< T * >
};
#endif
#if !defined(BOOST_NO_ARRAY_TYPE_SPECIALIZATIONS)
+/*
template <typename T, std::size_t N>
struct call_traits<T [N]>
{
@@ -165,6 +166,7 @@ public:
typedef const array_type& const_reference;
typedef const T* const param_type;
};
+*/
#endif
}I am using Cygwin, so maybe the problem is unique to me. But I don't know yet. One issue at a time. 😅 |
|
To be honest, I don't think docca/doxygen is going to be a good choice for Boost.Utility. When using docca you have to structure code in a certain way to accommodate the toolchain. For example, files in detail directories should be skipped. But Utility probably either lifts some symbols from a detail namespace, or declares symbols in the primary namespace in files in detail directories. This breaks assumptions. When you have a lot of code that hasn't been exposed to doxygen, very likely doxygen will emit faulty XML. And you have to painstakingly fix each piece of C++ code that doxygen is choking on. I instinctively know how to write new code that avoids this problem, because I have been working with docca for several years now and I am careful to run Doxygen frequently to identify problems the moment they appear. For now, I believe that trying to convert an ancient library like Boost.Utility to use Doxygen is going to be an exercise in frustration, and even if successful will require considerable change to the sources. I'm not sure its a net win for the amount of change, given that the Doxygen C++ parser is relatively weak, and that Boost authors love to push the language to its limits. |
|
Good to know! Even so... I'm close to eliminating all the broken links. In each case so far, it's a matter of making docca more robust and doesn't involve any weird workarounds. So I'll proceed for now with this issue and regroup as necessary if we keep running into too many issues. |
|
A number (though not all) of the broken links are due to duplicate declarations that aren't really overloads. We could remove duplicates at the very first stage of processing to make docca more robust. For example, see
This results in two identical entries in Doxygen's index.xml file: On one line: <member refid="classboost_1_1compressed__pair_1a05b29f866dcbca73330f11679e832a40" kind="typedef"><name>first_type</name></member>And on another line: <member refid="classboost_1_1compressed__pair_1a05b29f866dcbca73330f11679e832a40" kind="typedef"><name>first_type</name></member>We could make Doxygen/docca more robust by ignoring identical duplicates. @vinniefalco, let me know if you'd like me to proceed with this change. It would fix a large portion of the broken links. The other two fixes involved escaping commas and escaping ampersands, respectively. That leaves just one broken link (out of over 100) that I haven't investigated yet. This change should theoretically cause no harm but only good, but I can verify by testing it against all the libraries that use docca. It's not completely trivial, but it also shouldn't be difficult, and I should be able to do it in a plenty performant way. |
|
I agree with you both. The way Boost.Utility is structured doesn't help much. And I would also love to help docca as much as I can to make it more robust so we can use it for other libraries. At worst, this exercise has been helping us make docca more resilient even if we don't use it. It seems like Evan found the cause of most broken links which is stupendous.
I think I partially managed to solve that. I attempted to separate the details from the API by excluding a combination of files and symbols.
The proposal here is to abandon docca or to abandon both doxygen and docca? The new documentation would have no reference then? |
I don't know what I'm proposing, but it looks like we could be in for a lot of pain because the mix of Doxygen's poor parsing ability and Boost.Utility not being written with these Doxygen parsing quirks in mind.
The new documentation should have a reference, of course. If you guys think you can work through all the issues, then go for it. Maybe it can be done with effort. |
|
That makes sense. I guess there's no harm in looking at what the reference will look like after we get rid of these warnings and the table of contents looks a little better. |
|
Hi @evanlenz ,
I think you're getting an error at an earlier step for some reason. Probably something related to the OS. I've also included <replace pattern="," with="_comma_"/>in
The files have different names over here: structboost_1_1call__traits.xml Here is the complete list.
Great. I hope this one is something related to the OS only, considering the filenames are different. Maybe we could set up a VM with Ubuntu if we can't get the same warnings. The difference in the filenames could probably explain the first problem though.
That's interesting. For historical reasons, the files in I've attempted to remove these files in Not sure that completely worked. As @vinniefalco mentioned, it takes more effort to adapt a library that already exists than to write a library with doxygen + docca in mind. But ignoring identical duplicates, as you said, sounds much more robust. |
|
Some good news! 🎉 I've managed to put the reference in a child section so that the TOC looks cleaner while fixing the links in the subsection and getting the up arrows to work. The up arrows are not going to any blank pages anymore. For instance, the up arrow in this page goes back to the reference. It's looking quite good. We can even reuse this pattern in Boost.Json to remove that blank page from there. We only have a few broken links now, but they are in two groups and we know what they are:
I think @evanlenz already identified a fix for both of them. And I'll also add some macros to remove whatever is in |
|
More good news. No warnings left. The result looks good. All links are OK. The version without the warnings will only be correct in the preview because it required some local changes. We need some PRs to fix it permanently. That required <replace pattern="," with="_comma_"/>
<replace pattern="&" with="_ampersand_"/>in docca, so we need a PR for that. It's probably worth going through all HTML escaped chars that might cause errors and putting them there already. The compressed_pair duplicates were manually removed with macros for now. So we need one more PR for that. |
|
Excellent work! I am still working on the PR for all the broken-link issues. That includes the change you listed above, the treatment of friend sections as always public, and the duplicates removal. All are implemented and now I'm just verifying the changes across all the libraries to guard against regressions. (I suspect the bad-filename issue in the utility project will persist for me, but that sounds unique to my environment and I will have to address that separately.) Stay tuned... EDIT: I forgot to mention I am also seeing some remaining broken links in the Beast project; I need to confirm they are all editorial problems or otherwise fix additional broken-link bugs in docca. I don't want to close this issue until I've somehow addressed all known broken link issues. |
|
In order to ensure the bulk of this work isn't lost, I'm going to revisit, verify, and commit the relevant changes thus far. We can open a new issue to address any remaining broken links we might come across. |
|
Fixed by 8ba36c0 |
Description
The quickbook file generated by docca has a few warnings, such as
Error: no ID for constraint linkend: "utility.ref.boost__base_from_member_lt__MemberType_&,_UniqueID__gt_.base_from_member"..Preview
This output generated from these docs.
Replicating the issue
git clone -b docca_ref https://github.com/alandefreitas/utility.git cd utility/doc b2I'm still coming up with a smaller example to replicate the issue.
The text was updated successfully, but these errors were encountered: