docs: start writing standardese to propose to WG21

[JohelEGP]

Naturally, I offer myself to do the writing. Are there any sufficiently stable APIs to start with? Note that we could gloss over some things with _see below_s, unspecified's, and hand-wavy wording until they stabilize.

I want to start building consensus. To encourage earlier feedback with the components we can. Sending more proposals to WG21 should help with this. And hopefully spawn counter-proposals earlier rather than later. The visibility should also enable more constructive discussions to emerge.

[mpusz]

@JohelEGP, you are right. I will be in Kona, and I wanted to present the first papers there... but the v2 framework happened from something that was initially a simple dimensions handling refactoring. I think that we first need to finish it and get some experience with it. So I would wait with papers until New Jersey.

I just finished delivering 5 days full day trainings and I am now at the airport waiting for my plane to Londo to deliver 10 more days. I am not sure if I will have much time to work on V2 there but I hope to do some work. I hope to have everything done before Kona and discuss the new design there with some members of the Committee that are interested in supporting that proposal.

[mpusz]

With the amount of work that we started recently to support the ISO 80000 quantities, I am afraid we will not be able to deliver papers on time for C++26, especially if we will be working on two separate designs/libraries. The changes are huge, and we need some feedback from production or really good tests and examples to prove that the design is correct. Maybe we will have to wait for C++29 with the standardization...

[JohelEGP]

especially if we will be working on two separate designs/libraries

How do we balance things better to make forward progress on the W21's proposal? I think you mentioned something about updating the documentation in #391/#397, but I can't find them. And I haven't familiarized myself with these PRs, besides reviewing them.

[mpusz]

I didn't write any documentation yet. First, I would like all (or at least most) of the previous code to compile with the V2 framework. The problem is that I am extending the scope of refactoring every month. I thought that I was nearly done, and now I started to work on #405, which again significantly changed the design.

[mpusz]

In order to start writing standardeese we need to set up an API reference tool that will allow us to do so. I hoped to use Standardeese but I learned from the author that it has many issues with C++20 and that the tool in not maintained anymore. @JohelEGP if I recall correctly you had some other solution in mind?

[JohelEGP]

Yes. The solution is to write directly in LaTeX: https://github.com/JohelEGP/jegp/tree/master/doc. Just like where the reference documentation will be committed to: https://github.com/cplusplus/draft.

You can see the results of doing so at https://johelegp.github.io/ under "JEGP". That's the documentation for https://github.com/JohelEGP/jegp.

I setup CI to install the dependencies of https://github.com/cplusplus/draft and https://github.com/Eelis/cxxdraft-htmlgen at https://github.com/JohelEGP/jegp/blob/master/.travis.yml#L14-L24 and (https://github.com/JohelEGP/jegp/blob/master/.travis.yml#L97, https://github.com/JohelEGP/jegp/blob/master/travis/meet_doc_prereq.sh), respectively. I also setup GH pages to publish https://johelegp.github.io/.

The CMake buildsystem https://github.com/JohelEGP/jegp/blob/master/doc/CMakeLists.txt is used to build the PDF and HTML. https://github.com/JohelEGP/jegp/blob/master/travis/postprocess_doc.sh is also used to prepare the HTML for GH pages. The CMakeLists.txt uses branches of https://github.com/cplusplus/draft and https://github.com/Eelis/cxxdraft-htmlgen to change hard-coded references of "C++ Standard" to "JEGP Library" and disable unused things like some indexes. For demonstration, the branches are https://github.com/johelegp/draft/tree/jegp and https://github.com/johelegp/cxxdraft-htmlgen/tree/jegp. You can follow the "𝘕 commits head" link to see what is changed.

To simplify the process above, I have been working on https://github.com/JohelEGP/jegp.cmake_modules/tree/std-src#jegpaddstandardesesources. You still need a directory like https://github.com/JohelEGP/jegp/blob/master/doc/. But the CMakeLists.txt just has to look like this:

cmake_minimum_required(VERSION 3.25.0)
project(Waarudo_reference_documentations LANGUAGES NONE)

include(JEGPAddStandardeseSources)

set(pdf_title "Waarudo Library")
set(page_license "Unlicense")
set(first_library_chapter "serial")
set(last_library_chapter "exenv")
set(pdf_creator "Johel Ernesto Guerrero Pe\\~{n}a")
# set(document_number [[\unspec]])
# set(previous_document_number [[\unspec]])
set(cover_title "Waarudo Library Reference Documentations")
set(reply_to "\\href{${PROJECT_HOMEPAGE_URL}/discussions}{Discussions}, \\href{${PROJECT_HOMEPAGE_URL}/issues}{issues}")
jegp_add_standardese_sources(
  Waarudo_reference_documentations
  LIBRARIES intro;serialization numbers;quantities;geometries exenv
  EXTENSIONS bibliography macros_extensions
  CHECKED TRUE
  PDF_PATH "Waarudo.pdf")

It works to get a PDF, but HTML support is still in the works.

[mpusz]

The solution is to write directly in LaTeX:

Wow, that is so inconvenient :-(

• LaTeX is verbose and quite complicated for people that never did it
• This is not being kept together with the source code, so can't serve as an in-source API documentation

If we are about to write documentation in a separate repo probably one of the below popular utilities to write ISO papers should be considered:

• bikeshed
• Michael Parks' WG21

Most of the current proposals are written using those.

It is a pity that Standardeese is not maintained anymore 😢

[JohelEGP]

If we are about to write documentation in a separate repo

Why not under docs/reference?

[mpusz]

Right, I will think about this and take a closer look at LATeX (I was always scared of it :wink:).