Google Season of Docs
Hi, The registration for organization is now open. If anyone is interested in managing this project and wish to talk about now, please let me know. I've got some experience now managing the Google Summer of Code and can help with GSoD too. Cheers, David
I can do the management. I posted to the list a few days ago looking for interested mentors, but got no volunteers. El mar., 14 abr. 2020 a las 8:53, David Bellot via Boost (< boost@lists.boost.org>) escribió:
Hi,
The registration for organization is now open. If anyone is interested in managing this project and wish to talk about now, please let me know. I've got some experience now managing the Google Summer of Code and can help with GSoD too.
Cheers, David
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Hi, I would like to help with the organization as well if multiple organizers are allowed. Best, Cem Am Di., 14. Apr. 2020 um 23:37 Uhr schrieb Damian Vicino via Boost < boost@lists.boost.org>:
I can do the management. I posted to the list a few days ago looking for interested mentors, but got no volunteers.
El mar., 14 abr. 2020 a las 8:53, David Bellot via Boost (< boost@lists.boost.org>) escribió:
Hi,
The registration for organization is now open. If anyone is interested in managing this project and wish to talk about now, please let me know. I've got some experience now managing the Google Summer of Code and can help with GSoD too.
Cheers, David
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 4/14/20 5:52 AM, David Bellot via Boost wrote:
Hi,
The registration for organization is now open. If anyone is interested in managing this project and wish to talk about now, please let me know. I've got some experience now managing the Google Summer of Code and can help with GSoD too.
Cheers, David
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Has anyone manifested interest in actually writing documentation? If so, for what software? Robert Ramey
so far, Damian and Cem are interested to help on this project. On Sun, Apr 19, 2020 at 1:14 AM Robert Ramey via Boost < boost@lists.boost.org> wrote:
On 4/14/20 5:52 AM, David Bellot via Boost wrote:
Hi,
The registration for organization is now open. If anyone is interested in managing this project and wish to talk about now, please let me know. I've got some experience now managing the Google Summer of Code and can help with GSoD too.
Cheers, David
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Has anyone manifested interest in actually writing documentation? If so, for what software?
Robert Ramey
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Hi Robert, good question. I can only speak for Boost/numeric/ublas. Our documentation needs to be ported from pure html to rst code with sphinx. I would like to add examples and doxygen gegenerated reference section. Best, Cem Am Sa., 18. Apr. 2020 um 23:41 Uhr schrieb David Bellot via Boost < boost@lists.boost.org>:
so far, Damian and Cem are interested to help on this project.
On Sun, Apr 19, 2020 at 1:14 AM Robert Ramey via Boost < boost@lists.boost.org> wrote:
On 4/14/20 5:52 AM, David Bellot via Boost wrote:
Hi,
The registration for organization is now open. If anyone is interested in managing this project and wish to talk about now, please let me know. I've got some experience now managing the Google Summer of Code and can help with GSoD too.
Cheers, David
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Has anyone manifested interest in actually writing documentation? If so, for what software?
Robert Ramey
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
I'd be grateful is someone would take date-time docs in boost-book xml and translate them into quickbook. That could be a tool that it looks like several other library maintainers might be interested in. On Sun, Apr 19, 2020 at 6:39 AM Cem Bassoy via Boost <boost@lists.boost.org> wrote:
Hi Robert,
good question. I can only speak for Boost/numeric/ublas. Our documentation needs to be ported from pure html to rst code with sphinx. I would like to add examples and doxygen gegenerated reference section.
Best, Cem
Am Sa., 18. Apr. 2020 um 23:41 Uhr schrieb David Bellot via Boost < boost@lists.boost.org>:
so far, Damian and Cem are interested to help on this project.
On Sun, Apr 19, 2020 at 1:14 AM Robert Ramey via Boost < boost@lists.boost.org> wrote:
On 4/14/20 5:52 AM, David Bellot via Boost wrote:
Hi,
The registration for organization is now open. If anyone is interested in managing this project and wish to talk about now, please let me know. I've got some experience now managing the Google Summer of Code and can help with GSoD too.
Cheers, David
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Has anyone manifested interest in actually writing documentation? If so, for what software?
Robert Ramey
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 4/19/20 4:29 PM, Jeff Garland via Boost wrote:
I'd be grateful is someone would take date-time docs in boost-book xml and translate them into quickbook. That could be a tool that it looks like several other library maintainers might be interested in.
I had this very issue. I solved by using a boost book xml GUI editor - XmlMind. So every time I update the docs, it's a very simple task. a) no interaction with b2/boost-build b) no connection with other cool software which mostly works c) ability to produce html and/or PDF d) working with the boost book tool chain which has been working for at least 15 years. d) Just all around simpler. Robert Ramey
On Mon, 20 Apr 2020 at 01:29, Jeff Garland via Boost <boost@lists.boost.org> wrote:
I'd be grateful is someone would take date-time docs in boost-book xml and translate them into quickbook. That could be a tool that it looks like several other library maintainers might be interested in.
or to AsciiDoc, I guess. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
Mateusz Loskot via Boost <boost@lists.boost.org> schrieb am Mo. 20. Apr. 2020 um 10:28:
On Mon, 20 Apr 2020 at 01:29, Jeff Garland via Boost <boost@lists.boost.org> wrote:
I'd be grateful is someone would take date-time docs in boost-book xml
and
translate them into quickbook. That could be a tool that it looks like several other library maintainers might be interested in.
or to AsciiDoc, I guess.
Is GIL using AsciiDoc?
Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Mon, 20 Apr 2020 at 10:31, Cem Bassoy <cem.bassoy@gmail.com> wrote:
Mateusz Loskot via Boost <boost@lists.boost.org> schrieb am Mo. 20. Apr. 2020 um 10:28:
On Mon, 20 Apr 2020 at 01:29, Jeff Garland via Boost <boost@lists.boost.org> wrote:
I'd be grateful is someone would take date-time docs in boost-book xml and translate them into quickbook. That could be a tool that it looks like several other library maintainers might be interested in.
or to AsciiDoc, I guess.
Is GIL using AsciiDoc?
No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
Mateusz Loskot via Boost <boost@lists.boost.org> schrieb am Mo. 20. Apr. 2020 um 10:59:
Mateusz Loskot via Boost <boost@lists.boost.org> schrieb am Mo. 20. Apr. 2020 um 10:28:
On Mon, 20 Apr 2020 at 01:29, Jeff Garland via Boost <boost@lists.boost.org> wrote:
I'd be grateful is someone would take date-time docs in boost-book
xml and
translate them into quickbook. That could be a tool that it looks
On Mon, 20 Apr 2020 at 10:31, Cem Bassoy <cem.bassoy@gmail.com> wrote: like
several other library maintainers might be interested in.
or to AsciiDoc, I guess.
Is GIL using AsciiDoc?
No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think.
Can you shortly elaborate? I am asking for ublas.
Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
Mateusz Loskot wrote:
Cem Bassoy wrote:
Is GIL using AsciiDoc?
No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think.
Can you shortly elaborate? I am asking for ublas.
If you're interested, we've converted a few Boost library documentation from HTML to Asciidoc. For example: - Boost.Endian: Now: https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html Before: https://www.boost.org/doc/libs/1_70_0/libs/endian/doc/index.html - Boost.IO: Now: https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html Before: https://www.boost.org/doc/libs/1_72_0/libs/io/doc/index.html - Boost.Smart_Ptr: Now: https://www.boost.org/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html Before: https://www.boost.org/doc/libs/1_64_0/libs/smart_ptr/smart_ptr.htm The Asciidoc files and Jamfiles involved in these projects (and others - e.g. Boost.Mp11, Boost.Variant2, Boost.Assert, Boost.System are all Asciidoc too) should highlight how straightforward this would be if you choose to adopt it. The asciidoctor tool is also fairly easy to run for users to generate this documentation themselves, compared to Quickbook+Boostbook. I'm told it is simpler and easier to run than Sphinx too. Glen
On Mon, 20 Apr 2020 at 17:19, Glen Fernandes via Boost <boost@lists.boost.org> wrote:
On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
Mateusz Loskot wrote:
Cem Bassoy wrote:
Is GIL using AsciiDoc?
No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think.
Can you shortly elaborate? I am asking for ublas.
If you're interested, we've converted a few Boost library documentation from HTML to Asciidoc. [...] The asciidoctor tool is also fairly easy to run for users to generate this documentation themselves, compared to Quickbook+Boostbook. I'm told it is simpler and easier to run than Sphinx too.
Thank you Glen. Cem, my first issue with Sphinx is reST which, and Quickbook too, I find not as friendly for a human reader as I do find AsciiDoc. I like Markdown and AsciiDoc feels more like it and offers semantic features that I'm missing from Markdown. I also find Python legacies in Sphinx a bit itching - originally developed for Python, ported to other domains, while AsciiDoc and its tools feel domain-agnostic. OTOH, some argue Sphinx is more capable than AsciiDoctor here I found a good summary, may be outdated though https://github.com/neovim/neovim/issues/329#issuecomment-56082074 There are some interesting tools for AsciiDoc format, e.g. http://antora.org/ Finally, as Glen explained, some Boost libraries selected AsciiDoc, so it makes sense to me to follow the crowd to be able to share knowledge and any tools and infrastructure that appears in future. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
I'd be fine with AsciiDoc as well, but I'd say currently at least quickbook appears to be a much more frequent choice. The real question for the thread remains will we have someone do a project to convert xmldocs into one of the 'plain text' alternatives? On Mon, Apr 20, 2020 at 8:36 AM Mateusz Loskot via Boost < boost@lists.boost.org> wrote:
On Mon, 20 Apr 2020 at 17:19, Glen Fernandes via Boost <boost@lists.boost.org> wrote:
On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
Mateusz Loskot wrote:
Cem Bassoy wrote:
Is GIL using AsciiDoc?
No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think.
Can you shortly elaborate? I am asking for ublas.
If you're interested, we've converted a few Boost library documentation from HTML to Asciidoc. [...] The asciidoctor tool is also fairly easy to run for users to generate this documentation themselves, compared to Quickbook+Boostbook. I'm told it is simpler and easier to run than Sphinx too.
Thank you Glen.
Cem, my first issue with Sphinx is reST which, and Quickbook too, I find not as friendly for a human reader as I do find AsciiDoc. I like Markdown and AsciiDoc feels more like it and offers semantic features that I'm missing from Markdown. I also find Python legacies in Sphinx a bit itching - originally developed for Python, ported to other domains, while AsciiDoc and its tools feel domain-agnostic.
OTOH, some argue Sphinx is more capable than AsciiDoctor here I found a good summary, may be outdated though https://github.com/neovim/neovim/issues/329#issuecomment-56082074
There are some interesting tools for AsciiDoc format, e.g. http://antora.org/
Finally, as Glen explained, some Boost libraries selected AsciiDoc, so it makes sense to me to follow the crowd to be able to share knowledge and any tools and infrastructure that appears in future.
Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Mon, Apr 20, 2020 at 12:09 PM Jeff Garland via Boost <boost@lists.boost.org> wrote:
I'd be fine with AsciiDoc as well, but I'd say currently at least quickbook appears to be a much more frequent choice. The real question for the thread remains will we have someone do a project to convert xmldocs into one of the 'plain text' alternatives?
Sounds like an ideal thing for this Summer of Docs. Do we have a list of libraries that are still in: - Plain handwritten HTML - XML DateTime, Array, Iostreams, ... Glen
FWIW, I have converted some libraries to Quickbook and found it quite straightforward to copy and paste plain text paragraphs into a Quickbook section scaffold structure, and then make layout changes and add headings etc. You need a general index, and function, class, macro indexes too that are automatically generated from the Doxygen Syntax comments in the code. Providing snippets of working examples is the most valuable feature - in the knowledge that these really work on all platforms. IOM having lots and lots of examples are the most valuable part of all this. That's what people want - "How do I ... ? " By following examples, and seeking advice, it is pretty straight-forward, if time-consuming. I believe that the user experience is good. Paul
-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Jeff Garland via Boost Sent: 20 April 2020 17:08 To: Boost Developers List <boost@lists.boost.org> Cc: Jeff Garland <azswdude@gmail.com> Subject: Re: [boost] Google Season of Docs
I'd be fine with AsciiDoc as well, but I'd say currently at least quickbook appears to be a much more frequent choice. The real question for the thread remains will we have someone do a project to convert xmldocs into one of the 'plain text' alternatives?
On Mon, Apr 20, 2020 at 8:36 AM Mateusz Loskot via Boost < boost@lists.boost.org> wrote:
On Mon, 20 Apr 2020 at 17:19, Glen Fernandes via Boost <boost@lists.boost.org> wrote:
On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
Mateusz Loskot wrote:
Cem Bassoy wrote:
Is GIL using AsciiDoc?
No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think.
Can you shortly elaborate? I am asking for ublas.
If you're interested, we've converted a few Boost library documentation from HTML to Asciidoc. [...] The asciidoctor tool is also fairly easy to run for users to generate this documentation themselves, compared to Quickbook+Boostbook. I'm told it is simpler and easier to run than Sphinx too.
Thank you Glen.
Cem, my first issue with Sphinx is reST which, and Quickbook too, I find not as friendly for a human reader as I do find AsciiDoc. I like Markdown and AsciiDoc feels more like it and offers semantic features that I'm missing from Markdown. I also find Python legacies in Sphinx a bit itching - originally developed for Python, ported to other domains, while AsciiDoc and its tools feel domain-agnostic.
OTOH, some argue Sphinx is more capable than AsciiDoctor here I found a good summary, may be outdated though https://github.com/neovim/neovim/issues/329#issuecomment-56082074
There are some interesting tools for AsciiDoc format, e.g. http://antora.org/
Finally, as Glen explained, some Boost libraries selected AsciiDoc, so it makes sense to me to follow the crowd to be able to share knowledge and any tools and infrastructure that appears in future.
Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Dear Glen,
On 20. Apr 2020, at 17:18, Glen Fernandes via Boost <boost@lists.boost.org> wrote:
On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
Mateusz Loskot wrote:
Cem Bassoy wrote:
Is GIL using AsciiDoc?
No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think.
Can you shortly elaborate? I am asking for ublas.
If you're interested, we've converted a few Boost library documentation from HTML to Asciidoc. For example:
- Boost.Endian: Now: https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html Before: https://www.boost.org/doc/libs/1_70_0/libs/endian/doc/index.html
- Boost.IO: Now: https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html Before: https://www.boost.org/doc/libs/1_72_0/libs/io/doc/index.html
- Boost.Smart_Ptr: Now: https://www.boost.org/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html Before: https://www.boost.org/doc/libs/1_64_0/libs/smart_ptr/smart_ptr.htm
The Asciidoc files and Jamfiles involved in these projects (and others - e.g. Boost.Mp11, Boost.Variant2, Boost.Assert, Boost.System are all Asciidoc too) should highlight how straightforward this would be if you choose to adopt it. The asciidoctor tool is also fairly easy to run for users to generate this documentation themselves, compared to Quickbook+Boostbook. I'm told it is simpler and easier to run than Sphinx too.
thank you mentioning this. I am interested in switching from Quickbook to Asciidoc. I am mostly ok with Quickbook, but it is bothering me very much that I am required to close my sections with [endsect]. That is machine-friendly and not human-friendly. I also like the style for the Asciidoc docs with the TOC on the left. My main question: I generate my reference with doxygen in xml. The xml code is then post-processed using a Python script. The result is then integrated into my Quickbook docs(*) I quickly checked Jamfiles for the example libraries you mentioned, and none of those seem to have a doxygen-generated reference. How would I combine doxygen and Asciidoc? Best regards, Hans (*) How much annoyed I am by the inability of doxygen to produce a proper reference for a template-heavy lib like Boost.Histogram is another story, but I really don't want to write the reference by hand either and keep it in sync with code changes manually.
On Mon, Apr 20, 2020 at 1:59 PM Hans Dembinski <hans.dembinski@gmail.com> wrote:
My main question: I generate my reference with doxygen in xml. The xml code is then post- processed using a Python script. The result is then integrated into my Quickbook docs(*) I quickly checked Jamfiles for the example libraries you mentioned, and none of those seem to have a doxygen-generated reference. How would I combine doxygen and Asciidoc?
[...]
(*) How much annoyed I am by the inability of doxygen to produce a proper reference for a template-heavy lib like Boost.Histogram is another story, but I really don't want to write the reference by hand either and keep it in sync with code changes manually.
I don't have a solution for that, I'm afraid. As you've found, all of the above have reference documentation manually written. (I stopped using Doxygen even when Quickbook/Boostbook was involved, though so I never invested time in finding out how to make things work with Doxygen)
On Mon, Apr 20, 2020 at 3:38 PM Glen Fernandes via Boost < boost@lists.boost.org> wrote:
On Mon, Apr 20, 2020 at 1:59 PM Hans Dembinski <hans.dembinski@gmail.com> wrote:
My main question: I generate my reference with doxygen in xml. The xml code is then post- processed using a Python script. The result is then integrated into my Quickbook docs(*) I quickly checked Jamfiles for the example libraries you mentioned, and none of those seem to have a doxygen-generated reference. How would I combine doxygen and Asciidoc?
[...]
(*) How much annoyed I am by the inability of doxygen to produce a proper reference for a template-heavy lib like Boost.Histogram is another story, but I really don't want to write the reference by hand either and keep it in sync with code changes manually.
I don't have a solution for that, I'm afraid. As you've found, all of the above have reference documentation manually written. (I stopped using Doxygen even when Quickbook/Boostbook was involved, though so I never invested time in finding out how to make things work with Doxygen)
My long standing solution is to move the manual reference documentation as close as possible to the code itself. For example Predef uses asciidoctor and has a reference section. Which is embedded in the source code... Reference.. < https://www.boost.org/doc/libs/develop/libs/predef/doc/index.html#_reference
Doc source.. < https://github.com/boostorg/predef/blob/develop/include/boost/predef/compile...
-- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
Am Mo., 20. Apr. 2020 um 22:38 Uhr schrieb Glen Fernandes via Boost < boost@lists.boost.org>:
On Mon, Apr 20, 2020 at 1:59 PM Hans Dembinski <hans.dembinski@gmail.com> wrote:
My main question: I generate my reference with doxygen in xml. The xml code is then post- processed using a Python script. The result is then integrated into my Quickbook docs(*) I quickly checked Jamfiles for the example libraries you mentioned, and none of those seem to have a doxygen-generated reference. How would I combine doxygen and Asciidoc?
[...]
(*) How much annoyed I am by the inability of doxygen to produce a proper reference for a template-heavy lib like Boost.Histogram is another story, but I really don't want to write the reference by hand either and keep it in sync with code changes manually.
I don't have a solution for that, I'm afraid. As you've found, all of the above have reference documentation manually written. (I stopped using Doxygen even when Quickbook/Boostbook was involved, though so I never invested time in finding out how to make things work with Doxygen)
Yes, I am in doubt if Doxygen documentation is really a necessity for library users and developers. After seeing asciidoc and the simple document generation, I would like to go with asciidoc for Boost.ublas. I think, using C++ concepts will also help to better read and understand template code - maybe eliminating the necessity to document on a reference level. Thanks Glen. ------------- I would like to know the number of potential mentors for Google Summer of Docs <https://developers.google.com/season-of-docs>. For an example, see GSoD-Project-VLC <https://developers.google.com/season-of-docs/docs/2019/participants/project-videolan> Short summary of the *timeline*: Organization deadline is *May 4*. Technical writer exploration is between *May 11 and Jun 8* - Interested technical writers discuss project ideas with mentoring organizations Technical writing projects announcement* August 16, 2020* Community bonding *August 17 - September 13* Doc development *September 14, 2020 - November 30* Project finalization *November 30 - December 5* How many library contributors and maintainers would like to mentor professional technical writer? +1 for Boost.uBlas. P.S. There is also the chance to apply for a long-running project. Would that be helpful for Boost?
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
To the point on Doxygen -- sorry, but it is needed and used by some of us. I'm not saying we shouldn't do something that ignores that, but don't expect it to go away. On Wed, Apr 22, 2020 at 3:13 AM Cem Bassoy via Boost <boost@lists.boost.org> wrote:
Am Mo., 20. Apr. 2020 um 22:38 Uhr schrieb Glen Fernandes via Boost < boost@lists.boost.org>:
On Mon, Apr 20, 2020 at 1:59 PM Hans Dembinski <hans.dembinski@gmail.com
wrote:
My main question: I generate my reference with doxygen in xml. The xml code is then post- processed using a Python script. The result is then integrated into my Quickbook docs(*) I quickly checked Jamfiles for the example libraries you mentioned, and none of those seem to have a doxygen-generated reference. How would I combine doxygen and Asciidoc?
[...]
(*) How much annoyed I am by the inability of doxygen to produce a proper reference for a template-heavy lib like Boost.Histogram is another story, but I really don't want to write the reference by hand either and keep it in sync with code changes manually.
I don't have a solution for that, I'm afraid. As you've found, all of the above have reference documentation manually written. (I stopped using Doxygen even when Quickbook/Boostbook was involved, though so I never invested time in finding out how to make things work with Doxygen)
Yes, I am in doubt if Doxygen documentation is really a necessity for library users and developers. After seeing asciidoc and the simple document generation, I would like to go with asciidoc for Boost.ublas. I think, using C++ concepts will also help to better read and understand template code - maybe eliminating the necessity to document on a reference level. Thanks Glen.
-------------
I would like to know the number of potential mentors for Google Summer of Docs <https://developers.google.com/season-of-docs>. For an example, see GSoD-Project-VLC < https://developers.google.com/season-of-docs/docs/2019/participants/project-...
Short summary of the *timeline*: Organization deadline is *May 4*. Technical writer exploration is between *May 11 and Jun 8* - Interested technical writers discuss project ideas with mentoring organizations Technical writing projects announcement* August 16, 2020* Community bonding *August 17 - September 13* Doc development *September 14, 2020 - November 30* Project finalization *November 30 - December 5*
How many library contributors and maintainers would like to mentor professional technical writer?
+1 for Boost.uBlas.
P.S. There is also the chance to apply for a long-running project. Would that be helpful for Boost?
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Am Mi., 22. Apr. 2020 um 13:36 Uhr schrieb Jeff Garland via Boost < boost@lists.boost.org>:
To the point on Doxygen -- sorry, but it is needed and used by some of us. I'm not saying we shouldn't do something that ignores that, but don't expect it to go away.
Yes, I agree. Each mentor or maintainer should decide what's best for them. Did not want to suggest the "one and only" solution. Thanks for the hint! ----- I would like to raise my question again in order to keep the orignal topic: *I would like to know the number of potential mentors* for Google Summer of Docs <https://developers.google.com/season-of-docs>. For an example, see GSoD-Project-VLC <https://developers.google.com/season-of-docs/docs/2019/participants/project-videolan> Short summary of the *timeline*: Organization deadline is *May 4*. Technical writer exploration is between *May 11 and Jun 8* - Interested technical writers discuss project ideas with mentoring organizations Technical writing projects announcement* August 16, 2020* Community bonding *August 17 - September 13* Doc development *September 14, 2020 - November 30* Project finalization *November 30 - December 5* How many library contributors and maintainers would like to mentor professional technical writer? +1 for Boost.uBlas. P.S. There is also the chance to apply for a long-running project. Would that be helpful for Boost?
+1 Doxygen Syntax comments are THE standard way of describing expected code performance. Doxygen now understands C++ (using the Clang compiler so it really does ). What the parameters and template parameters do, what items are updated, what is returned, and of course, what a function does. (The magic of how and why may be an added bonus). Authors/documenters have to write this by hand - not just feed the code into Doxygen! (which is the delusion that many suffer from). Quickbook and other tools can process this info (because it has a known standard-ish syntax) and display it nicely. Paul
-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Jeff Garland via Boost Sent: 22 April 2020 12:36 To: Boost Developers List <boost@lists.boost.org> Cc: Jeff Garland <azswdude@gmail.com> Subject: Re: [boost] Google Season of Docs
To the point on Doxygen -- sorry, but it is needed and used by some of us. I'm not saying we shouldn't do something that ignores that, but don't expect it to go away.
On Wed, Apr 22, 2020 at 3:13 AM Cem Bassoy via Boost <boost@lists.boost.org> wrote:
Am Mo., 20. Apr. 2020 um 22:38 Uhr schrieb Glen Fernandes via Boost < boost@lists.boost.org>:
On Mon, Apr 20, 2020 at 1:59 PM Hans Dembinski <hans.dembinski@gmail.com
wrote:
My main question: I generate my reference with doxygen in xml. The xml code is then post- processed using a Python script. The result is then integrated into my Quickbook docs(*) I quickly checked Jamfiles for the example libraries you mentioned, and none of those seem to have a doxygen-generated reference. How would I combine doxygen and Asciidoc?
[...]
(*) How much annoyed I am by the inability of doxygen to produce a proper reference for a template-heavy lib like Boost.Histogram is another story, but I really don't want to write the reference by hand either and keep it in sync with code changes manually.
I don't have a solution for that, I'm afraid. As you've found, all of the above have reference documentation manually written. (I stopped using Doxygen even when Quickbook/Boostbook was involved, though so I never invested time in finding out how to make things work with Doxygen)
Yes, I am in doubt if Doxygen documentation is really a necessity for library users and developers. After seeing asciidoc and the simple document generation, I would like to go with asciidoc for Boost.ublas. I think, using C++ concepts will also help to better read and understand template code - maybe eliminating the necessity to document on a reference level. Thanks Glen.
-------------
I would like to know the number of potential mentors for Google Summer of Docs <https://developers.google.com/season-of-docs>. For an example, see GSoD-Project-VLC < https://developers.google.com/season-of-docs/docs/2019/participants/pr oject-videolan
Short summary of the *timeline*: Organization deadline is *May 4*. Technical writer exploration is between *May 11 and Jun 8* - Interested technical writers discuss project ideas with mentoring organizations Technical writing projects announcement* August 16, 2020* Community bonding *August 17 - September 13* Doc development *September 14, 2020 - November 30* Project finalization *November 30 - December 5*
How many library contributors and maintainers would like to mentor professional technical writer?
+1 for Boost.uBlas.
P.S. There is also the chance to apply for a long-running project. Would that be helpful for Boost?
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Dear Paul,
On 22. Apr 2020, at 14:55, Paul A Bristow via Boost <boost@lists.boost.org> wrote:
+1 Doxygen Syntax comments are THE standard way of describing expected code performance.
Doxygen now understands C++ (using the Clang compiler so it really does ).
What the parameters and template parameters do, what items are updated, what is returned, and of course, what a function does.
(The magic of how and why may be an added bonus).
Authors/documenters have to write this by hand - not just feed the code into Doxygen! (which is the delusion that many suffer from).
Quickbook and other tools can process this info (because it has a known standard-ish syntax) and display it nicely.
I wish it was so. Our toolchain does not handle meta-functions such as this: /** This is a meta-function. Bla bla. */ template <class T> using enable_if_t = .... The problem already exists in the XML code that the doxygen rule in a Jamfile generates. I don't know whether this is a problem with the rule or doxygen itself. The doxygen rule from Boost.Build is non-trivial and I haven't tried to run doxygen myself. I cannot read Boost.Build scripts very well, but it looks like the rule does some post-processing of the original XML. The workaround that I copied from other Boost libs is to do stuff like this #ifdef BOOST_HISTOGRAM_DOXYGEN_INVOKED // code that doxygen understands #else // actual code #endif This is, of course, terrible. If anyone has a better solution for this, I would love to document my meta-functions differently. There are other issues. Doxygen includes stuff that I don't want to show, unnamed template parameters, stuff that is in my boost::histogram::detail namespace, private member functions (although I configured it not to show them...). I have a Python script that does post-processing on the XML file produced by the doxygen rule in the Jamfile, where I fix all this, where I remove items marked as deprecated, and where I sort the headers in the reference alphabetically. All this should work out of the box. Best regards, Hans
On Wed, 22 Apr 2020 at 17:00, Hans Dembinski via Boost <boost@lists.boost.org> wrote:
On 22. Apr 2020, at 14:55, Paul A Bristow via Boost <boost@lists.boost.org> wrote:
+1 Doxygen Syntax comments are THE standard way of describing expected code performance.
Doxygen now understands C++ (using the Clang compiler so it really does ).
What the parameters and template parameters do, what items are updated, what is returned, and of course, what a function does.
(The magic of how and why may be an added bonus).
Authors/documenters have to write this by hand - not just feed the code into Doxygen! (which is the delusion that many suffer from).
Quickbook and other tools can process this info (because it has a known standard-ish syntax) and display it nicely.
I wish it was so. [...] There are other issues. [...] I have a Python script that does post-processing on the XML
Asio developed XSLT, Beast developed XSLT, Geometry initially developed XSLT, but switched to bespoke XML processor C++/Python. and these are not trivial solutions at all. Authors of new libraries will look at these and within 5 minutes decide to develop their own solution, I bet. Does that show the weakness of Doxygen? To me it somewhat does and the lack of Boost common solution is a motivation to avoid Doxygen. It may be a personal preference, but I very much dislike the (freedom of) variety of look & feel of documentation of Boost libraries. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Mateusz Loskot via Boost Sent: 22 April 2020 16:45 To: boost@lists.boost.org Cc: Mateusz Loskot <mateusz@loskot.net> Subject: Re: [boost] Google Season of Docs
On Wed, 22 Apr 2020 at 17:00, Hans Dembinski via Boost <boost@lists.boost.org> wrote:
On 22. Apr 2020, at 14:55, Paul A Bristow via Boost <boost@lists.boost.org> wrote:
+1 Doxygen Syntax comments are THE standard way of describing +expected code performance.
Doxygen now understands C++ (using the Clang compiler so it really does ).
What the parameters and template parameters do, what items are updated, what is returned, and of course, what a function does.
(The magic of how and why may be an added bonus).
Authors/documenters have to write this by hand - not just feed the code into Doxygen! (which is the delusion that many suffer from).
Quickbook and other tools can process this info (because it has a known standard-ish syntax) and display it nicely.
I wish it was so. [...] There are other issues. [...] I have a Python script that does post-processing on the XML
Asio developed XSLT, Beast developed XSLT, Geometry initially developed XSLT, but switched to bespoke XML processor C++/Python. and these are not trivial solutions at all.
Authors of new libraries will look at these and within 5 minutes decide to develop their own solution, I bet.
Definitely - NIH still rules the computing world☹ (NIH == Not Invented Here).
Does that show the weakness of Doxygen?
No - because almost no libraries use Doxygen as it should be used IMO. They do not add Doxygen syntax docs info *as they are writing the code*. And I absolutely sympathize - writing code is hard enough and documenting is a distraction. By the time one has got something working, energy to document is near zero ☹
To me it somewhat does and the lack of Boost common solution is a motivation to avoid Doxygen.
It may be a personal preference, but I very much dislike the (freedom of) variety of look & feel of documentation of Boost libraries.
Strongly agree - it's a mess - and that's why I would like to make the most popular toolchain work better, and be used better. But I've been bleating for years... and I'm stack-overflow with other projects already. Paul
On Wed, 22 Apr 2020 at 17:54, Paul A Bristow via Boost <boost@lists.boost.org> wrote:
On Wed, 22 Apr 2020 at 17:00, Hans Dembinski via Boost <boost@lists.boost.org> wrote:
On 22. Apr 2020, at 14:55, Paul A Bristow via Boost <boost@lists.boost.org> wrote:
+1 Doxygen Syntax comments are THE standard way of describing +expected code performance.
Doxygen now understands C++ (using the Clang compiler so it really does ).
What the parameters and template parameters do, what items are updated, what is returned, and of course, what a function does.
(The magic of how and why may be an added bonus).
Authors/documenters have to write this by hand - not just feed the code into Doxygen! (which is the delusion that many suffer from).
Quickbook and other tools can process this info (because it has a known standard-ish syntax) and display it nicely.
I wish it was so. [...] There are other issues. [...] I have a Python script that does post-processing on the XML
Asio developed XSLT, Beast developed XSLT, Geometry initially developed XSLT, but switched to bespoke XML processor C++/Python. and these are not trivial solutions at all.
Authors of new libraries will look at these and within 5 minutes decide to develop their own solution, I bet.
Definitely - NIH still rules the computing world☹ (NIH == Not Invented Here).
Does that show the weakness of Doxygen?
No - because almost no libraries use Doxygen as it should be used IMO. They do not add Doxygen syntax docs info *as they are writing the code*.
Do you mean use of the so called Doxygen Special Commands like @param, @tparam (or \-prefixed) ?
And I absolutely sympathize - writing code is hard enough and documenting is a distraction. By the time one has got something working, energy to document is near zero ☹
Yes, I've experienced that too.
To me it somewhat does and the lack of Boost common solution is a motivation to avoid Doxygen.
It may be a personal preference, but I very much dislike the (freedom of) variety of look & feel of documentation of Boost libraries.
Strongly agree - it's a mess - and that's why I would like to make the most popular toolchain work better, and be used better.
Seeing adoption of AsciiDoc by some core libraries, I've got a bit excited there may be tools helpful to integrate Doxygen well (e.g. doxygen2adoc perhaps), with a chance to be accepted Boost-wide. Apparently, those libs hand-roll API references, so no priority for Doxygen there. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
I think working in moving documentation from one tech used for writing it to another (ie. docbook to asciidoc) its not well tailored for a GSOD project. A good highschool student with enough motivation to do a lot of copy paste and formatting can do that during a google code-in project (or many). Also, after years of following this list I'm pretty sure we will not get half the maintainers to agree in a single tech to document anything. If we get a professional documenter, which is what GSOD provides, it should be for something where a good writer is required skill. ie. tutorials, new docs, completing docs with missed pieces of it. Analysing and fixing consistency in the writing across all libraries, etc...
Am Do., 23. Apr. 2020 um 04:24 Uhr schrieb Damian Vicino via Boost < boost@lists.boost.org>:
I think working in moving documentation from one tech used for writing it to another (ie. docbook to asciidoc) its not well tailored for a GSOD project.
You are right, although I have seen in some project that it was the main part.
A good highschool student with enough motivation to do a lot of copy paste and formatting can do that during a google code-in project (or many). Also, after years of following this list I'm pretty sure we will not get half the maintainers to agree in a single tech to document anything.
Agree.
If we get a professional documenter, which is what GSOD provides, it should be for something where a good writer is required skill. ie. tutorials, new docs, completing docs with missed pieces of it. Analysing and fixing consistency in the writing across all libraries, etc...
So you are thinking about a contribution for Boost not single libraries in general?
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Damian Vicino via Boost Sent: 23 April 2020 03:24 To: boost@lists.boost.org Cc: Damian Vicino <damian@vicino.com.ar> Subject: Re: [boost] Google Season of Docs
I think working in moving documentation from one tech used for writing it to another (ie. docbook to asciidoc) its not well tailored for a GSOD project. A good highschool student with enough motivation to do a lot of copy paste and formatting can do that during a google code-in project (or many). Also, after years of following this list I'm pretty sure we will not get half
the
maintainers to agree in a single tech to document anything.
Definitely. No chance. Almost every library has 'done their own thing' in various way, either by using a different tool, or by using an existing tool differently.
If we get a professional documenter, which is what GSOD provides, it should be for something where a good writer is required skill. ie. tutorials, new docs, completing docs with missed pieces of it. Analysing and fixing consistency in the writing across all libraries, etc...
The difference in type and scale means that 'one-size-fits-all' is unlikely to apply. Some are simple, others have many, many functions, some have tons of templates, others are mostly meta-magic... Have you looked at the difference in size between Boost.Math (near 20 MB) and Boost.Array (near 100 KB), for example? Paul
maintainers to agree in a single tech to document anything. Definitely. No chance.
Almost every library has 'done their own thing' in various way, either by using a different tool, or by using an existing tool differently. FWIW: I'd welcome something more standard. Like: You want Doxygen: Use this setup (Jamfile/CMakeLists) You want Asciidoc: Use that BoostBook?: Here you go
I know there is no "one size fits all", but maybe a "use this for code-heavy and that for template heavy libraries." Or just any guideline. I was a bit lost when I added the documentation for Nowide. I didn't want to install 3 or 4 different tools and go through 3 conversions just to get some docu done. Especially not if B2 magic is involved which can't be easily replicated in (e.g.) CMake Just my experience with current documentation workflow. If I got anything wrong: See it as exemplary how confusing it is ;) Alex
Am Do., 23. Apr. 2020 um 11:54 Uhr schrieb Alexander Grund via Boost < boost@lists.boost.org>:
maintainers to agree in a single tech to document anything. Definitely. No chance.
Almost every library has 'done their own thing' in various way, either by using a different tool, or by using an existing tool differently. FWIW: I'd welcome something more standard. Like: You want Doxygen: Use this setup (Jamfile/CMakeLists) You want Asciidoc: Use that BoostBook?: Here you go
I guess that this topic would not be the scope of GSoD. However, I think you will find good examples for each approach in the Boost libraries.
I know there is no "one size fits all", but maybe a "use this for code-heavy and that for template heavy libraries."
Or just any guideline. I was a bit lost when I added the documentation for Nowide. I didn't want to install 3 or 4 different tools and go through 3 conversions just to get some docu done. Especially not if B2 magic is involved which can't be easily replicated in (e.g.) CMake
This is the crux of the story. If it is so complicated to integrate such a toolchain or multiple tools, you are automatically thinking about the "pain" of using/linking and maintaing them. Ultimately, the degree of necessity and urgency determines the course of action - the willingness to integrate a hard-to-maintain-toolchain. If I think that Doxygen is not an ultimate necessity for my library and I am using AsciiDoc, I might want to postpone Doxygen-usage and the maintainance of a more complicated toolchain If it a big necessity for my library, I might want to switch to Sphinx with exhale/breathe additions including doxygen or search for or implement an addtional tool that can combine AsciiDoc with Doxygen. So, IMO, we do not need a howto for that as the howtos are already there (I agree sometimes also hard to find). With different libraries and requirements, time will show a convergence - maybe with multiple convergence points. I am not sure if there is a greatest common factor and if we can get something like a common look for all libraries. Are their parts of the Boost library documentation which could be restructured/renewed - not directly affecting the libraries?
Just my experience with current documentation workflow. If I got anything wrong: See it as exemplary how confusing it is ;)
Alex
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Cem Bassoy via Boost Sent: 23 April 2020 11:36 To: boost@lists.boost.org Cc: Cem Bassoy <cem.bassoy@gmail.com> Subject: Re: [boost] Google Season of Docs
Am Do., 23. Apr. 2020 um 11:54 Uhr schrieb Alexander Grund via Boost < boost@lists.boost.org>:
maintainers to agree in a single tech to document anything. Definitely. No chance.
Almost every library has 'done their own thing' in various way, either by using a different tool, or by using an existing tool differently. FWIW: I'd welcome something more standard. Like: You want Doxygen: Use this setup (Jamfile/CMakeLists) You want Asciidoc: Use that BoostBook?: Here you go
I guess that this topic would not be the scope of GSoD. However, I think you will find good examples for each approach in the Boost libraries.
I know there is no "one size fits all", but maybe a "use this for code-heavy and that for template heavy libraries."
Or just any guideline. I was a bit lost when I added the documentation for Nowide. I didn't want to install 3 or 4 different tools and go through 3 conversions just to get some docu done. Especially not if B2 magic is involved which can't be easily replicated in (e.g.) CMake
This is the crux of the story. If it is so complicated to integrate such a toolchain or multiple tools, you are automatically thinking about the "pain" of using/linking and maintaing them. Ultimately, the degree of necessity and urgency determines the course of action - the willingness to integrate a hard-to-maintain-toolchain.
If I think that Doxygen is not an ultimate necessity for my library and I am using AsciiDoc, I might want to postpone Doxygen-usage and the maintainance of a more complicated toolchain If it a big necessity for my library, I might want to switch to Sphinx with exhale/breathe additions including doxygen or search for or implement an addtional tool that can combine AsciiDoc with Doxygen.
So, IMO, we do not need a howto for that as the howtos are already there (I agree sometimes also hard to find). With different libraries and requirements, time will show a convergence - maybe with multiple convergence points. I am not sure if there is a greatest common factor and if we can get something
like
a common look for all libraries.
Are their parts of the Boost library documentation which could be restructured/renewed - not directly affecting the libraries?
I started a demo project on producing Quickbook/Doxygen docs, but more important things meant that it was pushed on the stack, and then, after stack overflow, it was 'lost'. My demo was good enough for simple libraries, but we haven't solved the complications from meta-magic - and most new libraries make use of these features. But I fear that this boat has sailed... ? Paul
On 22. Apr 2020, at 17:45, Mateusz Loskot via Boost <boost@lists.boost.org> wrote:
It may be a personal preference, but I very much dislike the (freedom of) variety of look & feel of documentation of Boost libraries.
For the record, I would also prefer a common look and feel. That's why I would convert to Asciidoc if the doxygen problem could be solved.
-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Hans Dembinski via Boost Sent: 23 April 2020 13:38 To: Boost Devs <boost@lists.boost.org> Cc: Hans Dembinski <hans.dembinski@gmail.com> Subject: Re: [boost] Google Season of Docs
On 22. Apr 2020, at 17:45, Mateusz Loskot via Boost <boost@lists.boost.org> wrote:
It may be a personal preference, but I very much dislike the (freedom of) variety of look & feel of documentation of Boost libraries.
For the record, I would also prefer a common look and feel. That's why I would convert to Asciidoc if the doxygen problem could be solved.
I would also much prefer a common look and feel, but there is zero possibility of converting Boost.Math to Asciidoc ... I'm sure you can guess why ... 😉 Paul
On Thu, Apr 23, 2020 at 9:31 AM Paul A Bristow via Boost < boost@lists.boost.org> wrote:
I would also much prefer a common look and feel, but there is zero possibility of converting Boost.Math to Asciidoc ...
Not that I disagree (and not advocating for common L&F, on that but..
I'm sure you can guess why ... 😉
No I can't guess.. Why is it? -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
El jue., 23 abr. 2020 a las 10:46, Rene Rivera via Boost (< boost@lists.boost.org>) escribió:
On Thu, Apr 23, 2020 at 9:31 AM Paul A Bristow via Boost < boost@lists.boost.org> wrote:
I would also much prefer a common look and feel, but there is zero possibility of converting Boost.Math to Asciidoc ...
Not that I disagree (and not advocating for common L&F, on that but..
I'm sure you can guess why ... 😉
No I can't guess.. Why is it?
I would guess asciidoc is not a friend of latex formulas :)
On Thu, Apr 23, 2020 at 9:32 PM Damian Vicino via Boost < boost@lists.boost.org> wrote:
El jue., 23 abr. 2020 a las 10:46, Rene Rivera via Boost (< boost@lists.boost.org>) escribió:
On Thu, Apr 23, 2020 at 9:31 AM Paul A Bristow via Boost < boost@lists.boost.org> wrote:
I would also much prefer a common look and feel, but there is zero possibility of converting Boost.Math to Asciidoc ...
Not that I disagree (and not advocating for common L&F, on that but..
I'm sure you can guess why ... 😉
No I can't guess.. Why is it?
I would guess asciidoc is not a friend of latex formulas :)
Haha. Asciidoctor loves those.. < https://asciidoctor.org/docs/user-manual/#stem> :-D -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
Just to take the conversation back to the original topic. Does someone want to mentor a project in GSOD?
No I can't guess.. Why is it?
I would guess asciidoc is not a friend of latex formulas :) Haha. Asciidoctor loves those.. < https://asciidoctor.org/docs/user-manual/#stem> :-D
I keep trying MathJax but can't find a way to love it - the main issue I see from Boost's documentation POV is that the scripts it runs get blocked by your browser unless they're run on the server - which is to say there's no offline viewing :( The other issue is the lack of support for inclusion of source files with intermixed documentation (what quickbook might call "reverse literate programming") which is invaluable for ensuring that code examples are both up to date and build correctly. I would also have to rewrite auto-index since that works on Docbook XML :( All that said, I can see that ASCIIDoc has progressed very significantly since I last looked at it. Best, John. -- This email has been checked for viruses by Avast antivirus software. https://www.avast.com/antivirus
On 2020-04-20 22:52, Rene Rivera via Boost wrote:
My long standing solution is to move the manual reference documentation as close as possible to the code itself. For example Predef uses asciidoctor and has a reference section. Which is embedded in the source code...
How does this work? Does asciidoctor scan the C++ header files and pick the stuff that looks like asciidoc?
On Thu, Apr 23, 2020 at 1:10 PM Bjorn Reese via Boost <boost@lists.boost.org> wrote:
On 2020-04-20 22:52, Rene Rivera via Boost wrote:
My long standing solution is to move the manual reference documentation as close as possible to the code itself. For example Predef uses asciidoctor and has a reference section. Which is embedded in the source code...
How does this work? Does asciidoctor scan the C++ header files and pick the stuff that looks like asciidoc?
You have to tell it what parts of the source code, it's language agnostic, to include in your asciidoctor output. < https://asciidoctor.org/docs/user-manual/#include-partial> -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Rene Rivera via Boost Sent: 23 April 2020 19:17 To: Boost Developers List <boost@lists.boost.org> Cc: Rene Rivera <grafikrobot@gmail.com> Subject: Re: [boost] Google Season of Docs
On Thu, Apr 23, 2020 at 1:10 PM Bjorn Reese via Boost <boost@lists.boost.org> wrote:
On 2020-04-20 22:52, Rene Rivera via Boost wrote:
My long standing solution is to move the manual reference documentation as close as possible to the code itself. For example Predef uses asciidoctor and has a reference section. Which is embedded in the source code...
How does this work? Does asciidoctor scan the C++ header files and pick the stuff that looks like asciidoc?
You have to tell it what parts of the source code, it's language agnostic, to include in your asciidoctor output. < https://asciidoctor.org/docs/user-manual/#include- partial>
IMO the perfect docs toll *must* understand C++ fully in order to provide quality automatic reference section production. Doxygen makes a good stab at that. But Boost libraries docs don't do that much even now. And I still can't find what I want to know quickly - even when I wrote it! And yes, Latex is the best tool for writing Math stuff, and we have not really cracked sucking in formulae properly in Boost.Math, though we have found a better method recently by converting LaTeX to an SVG image. Results are pretty, but it's a hassle still. Apart from being a yet-another-mark-up-language, what is *really* better about asciidoc? Speed? (I note that there are no instructions on running on Windows - but I suspect one can). Paul
Am Mo., 20. Apr. 2020 um 17:19 Uhr schrieb Glen Fernandes < glen.fernandes@gmail.com>:
On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
Mateusz Loskot wrote:
Cem Bassoy wrote:
Is GIL using AsciiDoc?
No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think.
Can you shortly elaborate? I am asking for ublas.
If you're interested, we've converted a few Boost library documentation from HTML to Asciidoc. For example:
- Boost.Endian: Now: https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html Before: https://www.boost.org/doc/libs/1_70_0/libs/endian/doc/index.html
- Boost.IO: Now: https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html Before: https://www.boost.org/doc/libs/1_72_0/libs/io/doc/index.html
- Boost.Smart_Ptr: Now: https://www.boost.orgsciidoc files and Jamfiles involved in these projects (a/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html <https://www.boost.org/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html> Before: https://www.boost.org/doc/libs/1_64_0/libs/smart_ptr/smart_ptr.htm
The Asciidoc files and Jamfiles involved in these projects (and others - e.g. Boost.Mp11, Boost.Variant2, Boost.Assert, Boost.System are all Asciidoc too) should highlight how straightforward this would be if you choose to adopt it. The asciidoctor tool is also fairly easy to run for users to generate this documentation themselves, compared to Quickbook+Boostbook. I'm told it is simpler and easier to run than Sphinx too.
I had a little bit of experience with sphinx using exhale and breathe. The output generation with the Jamfile seems to be simpler than with Sphinx. Is there a possibility to integrate doxygen reference like with sphinx using exhale and breathe? One could add an extra section for the reference hmtl, but only in the doxygen style. Maybe using an external converter. However, I haven't seen a reference section for Boost.IO/Boost.Endian/etc. (not needed?) Thanks, Cem
Glen
On Mon, Apr 20, 2020 at 4:23 PM Cem Bassoy <cem.bassoy@gmail.com> wrote:
However, I haven't seen a reference section for Boost.IO/Boost.Endian/etc. (not needed?)
They have reference documentation, it's just manually written in Asciidoc (no Doxygen involved). e.g. https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html#reference https://www.boost.org/doc/libs/1_72_0/libs/variant2/doc/html/variant2.html#r... https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html#conve... Glen
Sounds a good idea - IMO the best Boost documentation is written in Quickbook (and has reference info using Doxygen Syntax) and an Index. (but then I would say that wouldn't I 😉) Paul
-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Jeff Garland via Boost Sent: 20 April 2020 00:29 To: Boost Developers List <boost@lists.boost.org> Cc: Jeff Garland <azswdude@gmail.com> Subject: Re: [boost] Google Season of Docs
I'd be grateful is someone would take date-time docs in boost-book xml and translate them into quickbook. That could be a tool that it looks like several other library maintainers might be interested in.
On Sun, Apr 19, 2020 at 6:39 AM Cem Bassoy via Boost <boost@lists.boost.org> wrote:
Hi Robert,
good question. I can only speak for Boost/numeric/ublas. Our documentation needs to be ported from pure html to rst code with sphinx. I would like to add examples and doxygen gegenerated reference section.
Best, Cem
Am Sa., 18. Apr. 2020 um 23:41 Uhr schrieb David Bellot via Boost < boost@lists.boost.org>:
so far, Damian and Cem are interested to help on this project.
On Sun, Apr 19, 2020 at 1:14 AM Robert Ramey via Boost < boost@lists.boost.org> wrote:
On 4/14/20 5:52 AM, David Bellot via Boost wrote:
Hi,
The registration for organization is now open. If anyone is interested in managing this project and wish to talk about now, please let me know. I've got some experience now managing the Google Summer of Code and can help with GSoD too.
Cheers, David
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Has anyone manifested interest in actually writing documentation? If so, for what software?
Robert Ramey
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
participants (13)
-
Alexander Grund -
Bjorn Reese -
Cem Bassoy -
Damian Vicino -
David Bellot -
Glen Fernandes -
Hans Dembinski -
Jeff Garland -
John Maddock -
Mateusz Loskot -
pbristow＠hetp.u-net.com -
Rene Rivera -
Robert Ramey