There is a list of maintainers for Boost libraries at libs/maintainers.txt. Is there likewise a list of maintainers for Boost tools ? I have discovered a serious bug with BoostBook and nested namespaces, created an issue, but fear that no one will respond. I would like to e-mail anybody who is a maintainer for BoostBook who might be able to look at the issue and fix it, but there is no list of maintainers for Boost tools which I can find. The person who appears to have worked with BoostBook in the past, Daniel James, is no longer active with Boost so I have no idea who might be able to fix the issue.
On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote:
I have discovered a serious bug with BoostBook and nested namespaces, created an issue, but fear that no one will respond. I would like to e-mail anybody who is a maintainer for BoostBook who might be able to look at the issue and fix it, but there is no list of maintainers for Boost tools which I can find. The person who appears to have worked with BoostBook in the past, Daniel James, is no longer active with Boost so I have no idea who might be able to fix the issue.
BoostBook has no active maintainer right now. Glen
On 5/25/2021 2:00 PM, Glen Fernandes via Boost wrote:
On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote:
I have discovered a serious bug with BoostBook and nested namespaces, created an issue, but fear that no one will respond. I would like to e-mail anybody who is a maintainer for BoostBook who might be able to look at the issue and fix it, but there is no list of maintainers for Boost tools which I can find. The person who appears to have worked with BoostBook in the past, Daniel James, is no longer active with Boost so I have no idea who might be able to fix the issue.
BoostBook has no active maintainer right now.
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
On 5/26/21 7:46 PM, Edward Diener via Boost wrote:
On 5/25/2021 2:00 PM, Glen Fernandes via Boost wrote:
On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote:
I have discovered a serious bug with BoostBook and nested namespaces, created an issue, but fear that no one will respond. I would like to e-mail anybody who is a maintainer for BoostBook who might be able to look at the issue and fix it, but there is no list of maintainers for Boost tools which I can find. The person who appears to have worked with BoostBook in the past, Daniel James, is no longer active with Boost so I have no idea who might be able to fix the issue.
BoostBook has no active maintainer right now.
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
We have libraries that use QuickBook+Doxygen (I'm a maintainer of at least two), so you're definitely not alone. At least, in Boost.Log I have multiple nested namespaces, and I don't remember having a problem of symbols not documented in the nested namespaces. That said, I haven't built the docs locally for some time, so maybe something got broken...
On 5/26/2021 1:03 PM, Andrey Semashev via Boost wrote:
On 5/26/21 7:46 PM, Edward Diener via Boost wrote:
On 5/25/2021 2:00 PM, Glen Fernandes via Boost wrote:
On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote:
I have discovered a serious bug with BoostBook and nested namespaces, created an issue, but fear that no one will respond. I would like to e-mail anybody who is a maintainer for BoostBook who might be able to look at the issue and fix it, but there is no list of maintainers for Boost tools which I can find. The person who appears to have worked with BoostBook in the past, Daniel James, is no longer active with Boost so I have no idea who might be able to fix the issue.
BoostBook has no active maintainer right now.
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
We have libraries that use QuickBook+Doxygen (I'm a maintainer of at least two), so you're definitely not alone. At least, in Boost.Log I have multiple nested namespaces, and I don't remember having a problem of symbols not documented in the nested namespaces. That said, I haven't built the docs locally for some time, so maybe something got broken...
Could you try building your docs locally with the latest 'develop' branch ? Can you try the example at https://github.com/boostorg/boostbook/issues/10 and see if you are also seeing what I am seeing ?
On 5/26/21 8:30 PM, Edward Diener via Boost wrote:
On 5/26/2021 1:03 PM, Andrey Semashev via Boost wrote:
On 5/26/21 7:46 PM, Edward Diener via Boost wrote:
On 5/25/2021 2:00 PM, Glen Fernandes via Boost wrote:
On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote:
I have discovered a serious bug with BoostBook and nested namespaces, created an issue, but fear that no one will respond. I would like to e-mail anybody who is a maintainer for BoostBook who might be able to look at the issue and fix it, but there is no list of maintainers for Boost tools which I can find. The person who appears to have worked with BoostBook in the past, Daniel James, is no longer active with Boost so I have no idea who might be able to fix the issue.
BoostBook has no active maintainer right now.
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
We have libraries that use QuickBook+Doxygen (I'm a maintainer of at least two), so you're definitely not alone. At least, in Boost.Log I have multiple nested namespaces, and I don't remember having a problem of symbols not documented in the nested namespaces. That said, I haven't built the docs locally for some time, so maybe something got broken...
Could you try building your docs locally with the latest 'develop' branch ?
I get errors "Error: no ID for constraint linkend" that I remember having before (https://github.com/boostorg/quickbook/issues/11), but other than that the build succeeds. The generated reference section contains expected symbols (the few I checked, anyway).
Can you try the example at https://github.com/boostorg/boostbook/issues/10 and see if you are also seeing what I am seeing ?
Yes, the example::detail::example_value class template is not present in the final docs. However, if I rename the namespace to e.g. detail_ns then example_value is present in the output. I think, this has something to do with the boost.doxygen.detailns parameter, which is "detail" by default and is supposed to denote the namespace with implementation details that have to be omitted from the docs. However, setting it to a different value in the Jamfile didn't work for me, so ether it's something different or the user-specified value does not apply for some reason.
On 5/26/21 10:22 PM, Andrey Semashev wrote:
On 5/26/21 8:30 PM, Edward Diener via Boost wrote:
On 5/26/2021 1:03 PM, Andrey Semashev via Boost wrote:
On 5/26/21 7:46 PM, Edward Diener via Boost wrote:
On 5/25/2021 2:00 PM, Glen Fernandes via Boost wrote:
On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote:
I have discovered a serious bug with BoostBook and nested namespaces, created an issue, but fear that no one will respond. I would like to e-mail anybody who is a maintainer for BoostBook who might be able to look at the issue and fix it, but there is no list of maintainers for Boost tools which I can find. The person who appears to have worked with BoostBook in the past, Daniel James, is no longer active with Boost so I have no idea who might be able to fix the issue.
BoostBook has no active maintainer right now.
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
We have libraries that use QuickBook+Doxygen (I'm a maintainer of at least two), so you're definitely not alone. At least, in Boost.Log I have multiple nested namespaces, and I don't remember having a problem of symbols not documented in the nested namespaces. That said, I haven't built the docs locally for some time, so maybe something got broken...
Could you try building your docs locally with the latest 'develop' branch ?
I get errors "Error: no ID for constraint linkend" that I remember having before (https://github.com/boostorg/quickbook/issues/11), but other than that the build succeeds. The generated reference section contains expected symbols (the few I checked, anyway).
Can you try the example at https://github.com/boostorg/boostbook/issues/10 and see if you are also seeing what I am seeing ?
Yes, the example::detail::example_value class template is not present in the final docs. However, if I rename the namespace to e.g. detail_ns then example_value is present in the output.
I think, this has something to do with the boost.doxygen.detailns parameter, which is "detail" by default and is supposed to denote the namespace with implementation details that have to be omitted from the docs. However, setting it to a different value in the Jamfile didn't work for me, so ether it's something different or the user-specified value does not apply for some reason.
Ah, I added the parameter at the wrong place initially, so it didn't work. If you add "<xsl:param>boost.doxygen.detailns=aux" to the "doxygen example_reference" rule requirements, along with other <doxygen:param> tags, the example_value appears in the output. Here, "aux" is the detail namespace name you want to hide. BTW, the parameter is defined here: https://github.com/boostorg/boostbook/blob/aa3d1d676ce2d921dc820bbea9ed38a39...
On 5/26/2021 3:41 PM, Andrey Semashev via Boost wrote:
On 5/26/21 10:22 PM, Andrey Semashev wrote:
On 5/26/21 8:30 PM, Edward Diener via Boost wrote:
On 5/26/2021 1:03 PM, Andrey Semashev via Boost wrote:
On 5/26/21 7:46 PM, Edward Diener via Boost wrote:
On 5/25/2021 2:00 PM, Glen Fernandes via Boost wrote:
On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote: > I have discovered a serious bug with BoostBook and nested > namespaces, > created an issue, but fear that no one will respond. I would like to > e-mail anybody who is a maintainer for BoostBook who might be > able to > look at the issue and fix it, but there is no list of maintainers > for > Boost tools which I can find. The person who appears to have > worked with > BoostBook in the past, Daniel James, is no longer active with > Boost so I > have no idea who might be able to fix the issue.
BoostBook has no active maintainer right now.
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
We have libraries that use QuickBook+Doxygen (I'm a maintainer of at least two), so you're definitely not alone. At least, in Boost.Log I have multiple nested namespaces, and I don't remember having a problem of symbols not documented in the nested namespaces. That said, I haven't built the docs locally for some time, so maybe something got broken...
Could you try building your docs locally with the latest 'develop' branch ?
I get errors "Error: no ID for constraint linkend" that I remember having before (https://github.com/boostorg/quickbook/issues/11), but other than that the build succeeds. The generated reference section contains expected symbols (the few I checked, anyway).
Can you try the example at https://github.com/boostorg/boostbook/issues/10 and see if you are also seeing what I am seeing ?
Yes, the example::detail::example_value class template is not present in the final docs. However, if I rename the namespace to e.g. detail_ns then example_value is present in the output.
I think, this has something to do with the boost.doxygen.detailns parameter, which is "detail" by default and is supposed to denote the namespace with implementation details that have to be omitted from the docs. However, setting it to a different value in the Jamfile didn't work for me, so ether it's something different or the user-specified value does not apply for some reason.
Ah, I added the parameter at the wrong place initially, so it didn't work.
If you add "<xsl:param>boost.doxygen.detailns=aux" to the "doxygen example_reference" rule requirements, along with other <doxygen:param> tags, the example_value appears in the output. Here, "aux" is the detail namespace name you want to hide.
BTW, the parameter is defined here:
https://github.com/boostorg/boostbook/blob/aa3d1d676ce2d921dc820bbea9ed38a39...
Thank you very much, Andrey. I am not intending to criticize Daniel James but evidently his idea of documentation for BoostBook on the level of xsl parameters was "read the source". I am, however, really happy that you figured it out.
On Wed, May 26, 2021 at 7:02 PM Edward Diener via Boost <boost@lists.boost.org> wrote:
On 5/26/2021 3:41 PM, Andrey Semashev via Boost wrote:
If you add "<xsl:param>boost.doxygen.detailns=aux" to the "doxygen example_reference" rule requirements, along with other <doxygen:param> tags, the example_value appears in the output. Here, "aux" is the detail namespace name you want to hide.
Thank you very much, Andrey. I am not intending to criticize Daniel James but evidently his idea of documentation for BoostBook on the level of xsl parameters was "read the source". I am, however, really happy that you figured it out.
All of that (including the detail namespace hiding feature) was implemented by Doug (Gregor) 18 years ago. Many years before Daniel started contributing to it. Glen
On 5/27/2021 1:52 AM, Glen Fernandes via Boost wrote:
On Wed, May 26, 2021 at 7:02 PM Edward Diener via Boost <boost@lists.boost.org> wrote:
On 5/26/2021 3:41 PM, Andrey Semashev via Boost wrote:
If you add "<xsl:param>boost.doxygen.detailns=aux" to the "doxygen example_reference" rule requirements, along with other <doxygen:param> tags, the example_value appears in the output. Here, "aux" is the detail namespace name you want to hide.
Thank you very much, Andrey. I am not intending to criticize Daniel James but evidently his idea of documentation for BoostBook on the level of xsl parameters was "read the source". I am, however, really happy that you figured it out.
All of that (including the detail namespace hiding feature) was implemented by Doug (Gregor) 18 years ago. Many years before Daniel started contributing to it.
OK, my bad. A problem is that what was done is just not documented anywhere that I can see as far as the various BoostBook xsl options are concerned. It should not be necessary to read source files to understand how a library or a tool works.
On Wed, May 26, 2021 at 12:04 PM Andrey Semashev via Boost < boost@lists.boost.org> wrote:
On 5/26/21 7:46 PM, Edward Diener via Boost wrote:
On 5/25/2021 2:00 PM, Glen Fernandes via Boost wrote:
On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote:
I have discovered a serious bug with BoostBook and nested namespaces, created an issue, but fear that no one will respond. I would like to e-mail anybody who is a maintainer for BoostBook who might be able to look at the issue and fix it, but there is no list of maintainers for Boost tools which I can find. The person who appears to have worked with BoostBook in the past, Daniel James, is no longer active with Boost so I have no idea who might be able to fix the issue.
BoostBook has no active maintainer right now.
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
We have libraries that use QuickBook+Doxygen (I'm a maintainer of at least two), so you're definitely not alone. At least, in Boost.Log I have multiple nested namespaces, and I don't remember having a problem of symbols not documented in the nested namespaces. That said, I haven't built the docs locally for some time, so maybe something got broken...
One key aspect I noticed while debugging the b2 side of this.. That missing nested class is a "detail" namespace. And there might be some built-in filtering for those. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
On 2021-05-26 12:46 p.m., Edward Diener via Boost wrote:
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
That's one of the main reason why I have always argued against in-house tools. Alternatives (such as sphinx or mcdocs) may have their own bugs, but they do have the advantage of having a (much) bigger community, so a maintainer disappearing is much less likely to become an issue. Stefan -- ...ich hab' noch einen Koffer in Berlin...
On Wed, 26 May 2021 at 20:58, Stefan Seefeld via Boost <boost@lists.boost.org> wrote:
On 2021-05-26 12:46 p.m., Edward Diener via Boost wrote:
Too bad, as the bug will not be fixed. Am I really the only person using the quickbook/boostbook/doxygen toolchains to document a library with doxygen documentation for entities in a nested namespace ? It seems so. I guess I will have to except the fact that the nested namespace entities will never be documented in the doxygen-generated reference for a library.
That's one of the main reason why I have always argued against in-house tools. Alternatives (such as sphinx
Sphinx is a very good alternative to our in-house indeed Here is a good intro to the Sphinx stack: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with...
or mcdocs)
I've looked into mkdocs, and I use it at work, but for a library documentation tool, it's too basic, IMO. Alternative, which I'm yet to try myself, is the AsciiDoc+AsciiDoctor + https://asciidoxy.org BTW, AsciiDoc is getting momentum in Boost too.
may have their own bugs, but they do have the advantage of having a (much) bigger community, so a maintainer disappearing is much less likely to become an issue.oost
:heavy_check_mark: Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
participants (6)
-
Andrey Semashev -
Edward Diener -
Glen Fernandes -
Mateusz Loskot -
René Ferdinand Rivera Morell -
Stefan Seefeld