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

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

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 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 Mon, 20 Apr 2020 at 01:29, 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.

or to AsciiDoc, I guess. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On Mon, 20 Apr 2020 at 10:31, Cem Bassoy wrote:

Mateusz Loskot via Boost schrieb am Mo. 20. Apr. 2020 um 10:28:

...

On Mon, 20 Apr 2020 at 01:29, 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.

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

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

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

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 On Behalf Of Jeff Garland via Boost Sent: 20 April 2020 17:08 To: Boost Developers List Cc: Jeff Garland 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 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

On Mon, Apr 20, 2020 at 1:59 PM Hans Dembinski 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)

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

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

Dear Paul,

On 22. Apr 2020, at 14:55, Paul A Bristow via Boost 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

-----Original Message----- From: Boost On Behalf Of Mateusz Loskot via Boost Sent: 22 April 2020 16:45 To: boost@lists.boost.org Cc: Mateusz Loskot Subject: Re: [boost] Google Season of Docs

On Wed, 22 Apr 2020 at 17:00, Hans Dembinski via Boost wrote:

...

...

On 22. Apr 2020, at 14:55, Paul A Bristow via Boost 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

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

-----Original Message----- From: Boost On Behalf Of Damian Vicino via Boost Sent: 23 April 2020 03:24 To: boost@lists.boost.org Cc: Damian Vicino 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

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

On 22. Apr 2020, at 17:45, Mateusz Loskot via Boost 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.

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

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

...

...

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 Thu, Apr 23, 2020 at 1:10 PM Bjorn Reese via Boost 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

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

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 On Behalf Of Jeff Garland via Boost Sent: 20 April 2020 00:29 To: Boost Developers List Cc: Jeff Garland 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 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