Add a requirements section to usage.adoc

[gennaroprota]

No description provided.

[cppalliance-bot]

An automated preview of the documentation is available at https://1049.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2025-10-03 16:27:15 UTC

[ashtum]

I think AsciiDoc files have issues with C++ strings (they emit the plus signs), so we have to use {cpp} instead.

[gennaroprota]

Indeed. I had noticed in the docs preview that C++ had become C without classes again :-). Thanks, I'll fix it right away.

[alandefreitas]

Isn't that information like everywhere in the documentation over and over again already?

[gennaroprota]

@vinniefalco wanted an explicit statement about the IFNDR case.

[alandefreitas]

@vinniefalco That's the pattern I was attempting to communicate earlier today, which also just happened in #1048 and many others: a design discussion about problem X, where solution Y is proposed, is (reasonably) interpreted as an order to implement Y regardless of X.

The issues and PRs don't even bother to mention what problem X they're attempting to solve, and any attempt to even understand what's happening is futile because "Vinnie told me so" is, to be fair, a somewhat reasonable answer.

[vinniefalco]

The motivation for this change is the need to fully explain to the user what the requirements are for the input program. It has to compile with latest clang. It has to be well-formed, and in particular we require that symbols with the same name have the identical declarations. Unfortunately, it is possible to create a program where the same type has different declarations in different files and still get it to compile and link, without a diagnostic. And in some cases this could be valid C++ (or close to it). Yet for Mr. Docs it is catastrophic because of how we merge things from different translation units into the same corpus data structure.

This needs to be explained to the user, so when someone has a problem we can point them to the docs and say "does your program meet these requirements."

[alandefreitas]

I completely agree the requirements should be clear to user. It's extremely important for users to understand this difference from doxygen as soon as possible. In fact, this content should probably move to the beginning of this page or be exposed much sooner.

However, the problem I was previously mentioning with this issue is not the that requirements should not be listed. The problems I mentioned were:

1. The form the section is included in the page: In this particular issue is the requirement list has a single requirement and this very page already includes a gigantic section about this requirement. This PR completely ignores what already exists. The gigantic section is already explaining not only this requirement but also includes all common strategies in MrDocs to deal with it. At the very least, the new content should make sense in the context of the content that already exists and not be some copy/paste section content completely unrelated to the flow of the text. Otherwise, we have two sequent sections talking about the same thing.
2. And then the more general recurring problem of these "because-vinnie-told-me-so" issues and PR that are impossible to review, but I'm not going to be repetitive here because I believe we're already working on this problem in parallel.